Package 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 Details

  • Constructor Details

  • Method Details

    • getExportedObject

      public abstract DBusInterface getExportedObject(String _source, 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(String _source, String _path, 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> 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 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 String getMachineId()
      The generated UUID of this machine.
      Returns:
      String

    • 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

    • listen

      protected void listen()
      Start reading and sending messages.

    • getExportedObject

      public String getExportedObject(DBusInterface _interface) throws DBusException
      Throws:
      DBusException

    • 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(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.

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

    • 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(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 IOException
      Disconnect this session (for use in try-with-resources).
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      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 _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.

    • createTypesArray

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

    • handleException

      protected void handleException(Message _methodOrSignal, DBusExecutionException _exception)

    • handleMessage

      void handleMessage(Message _message) throws DBusException
      Handle received message from DBus.
      Parameters:
      _message -
      Throws:
      DBusException

    • handleMessage

      private void handleMessage(MethodCall _methodCall) throws DBusException
      Throws:
      DBusException

    • 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, Method _method, CallbackHandler<?> _callback)

    • sendMessageInternally

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

    • readIncoming

      Message readIncoming() throws DBusException
      Throws:
      DBusException

    • getExportedObjects

      protected Map<String,ExportedObject> getExportedObjects()

    • getFallbackContainer

      FallbackContainer getFallbackContainer()

    • 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<DBusMatchRule,Queue<DBusSigHandler<? extends DBusSignal>>> getHandledSignals()

    • getGenericHandledSignals

      protected Map<DBusMatchRule,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

    • 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 String toString()
      Overrides:
      toString in class Object