Class DBusMatchRuleBuilder

java.lang.Object
org.freedesktop.dbus.matchrules.DBusMatchRuleBuilder
public final class DBusMatchRuleBuilder extends Object
Builder to configure a DBusMatchRule.
Since:
5.2.0 - 2025-05-01
Author:
hypfvieh

  • Method Details

    • withSender

      public DBusMatchRuleBuilder withSender(String _sender)
      Set sender filter.

      Possible values: A bus (e.g. org.freedesktop.Hal) or unique name (e.g. :1.2)

      Parameters:
      _sender - sender to filter, null to remove
      Returns:
      this

    • withDestination

      public DBusMatchRuleBuilder withDestination(String _destination)
      Set destination filter.

      DBus Specification Quote:

      Matches messages which are being sent to the given unique name. An example of a destination match is destination=':1.0'

      Parameters:
      _destination - destination to filter, null to remove
      Returns:
      this

    • withPath

      public DBusMatchRuleBuilder withPath(String _path)
      Set path filter.

      DBus Specification Quote:

      Matches messages which are sent from or to the given object. An example of a path match is path='/org/freedesktop/Hal/Manager'

      Parameters:
      _path - path to filter, null to remove
      Returns:
      this
      Throws:
      IllegalArgumentException - when path_namespace already set

    • withInterface

      public DBusMatchRuleBuilder withInterface(String _interface)
      Set interface filter.

      DBus Specification Quote:

      Match messages sent over or to a particular interface. An example of an interface match is interface='org.freedesktop.Hal.Manager'. If a message omits the interface header, it must not match any rule that specifies this key.

      Parameters:
      _interface - interface to filter, null to remove
      Returns:
      this

    • withMember

      public DBusMatchRuleBuilder withMember(String _member)
      Set member/name filter.

      DBus Specification Quote:

      Matches messages which have the give method or signal name. An example of a member match is member='NameOwnerChanged'

      Parameters:
      _member - member/name to filter, null to remove
      Returns:
      this

    • withType

      public DBusMatchRuleBuilder withType(String _type)
      Set message type filter.

      Possible values: 'signal', 'method_call', 'method_return', 'error'

      DBus Specification Quote:

      Match on the message type. An example of a type match is type='signal'

      Parameters:
      _type - message type to filter, null to remove
      Returns:
      this
      Throws:
      IllegalArgumentException - when invalid message type is given

    • withType

      public DBusMatchRuleBuilder withType(MessageTypes _type)
      Set type filter using MessageTypes enum.
      Parameters:
      _type - type to filter, null to remove
      Returns:
      this

    • withType

      public DBusMatchRuleBuilder withType(Class<?> _clz) throws DBusException
      Set message type filter using class.

      Class must be a DBusInterface compatible or Error/DBusSignal class.

      Parameters:
      _clz - class to use for setting up filter, null to remove
      Returns:
      this
      Throws:
      DBusException - when invalid class s given

    • withArg0123

      public DBusMatchRuleBuilder withArg0123(int _argId, String _arg0123)
      Set/add argument filter.

      DBus Specification Quote:

      Arg matches are special and are used for further restricting the match based on the arguments in the body of a message. Only arguments of type STRING can be matched in this way. An example of an argument match would be arg3='Foo'. Only argument indexes from 0 to 63 should be accepted.

      Parameters:
      _argId - argument number
      _arg0123 - argument value to filter, null to remove
      Returns:
      this

    • withArg0123Path

      public DBusMatchRuleBuilder withArg0123Path(int _argId, String _arg0123Path)
      Set argument path filter.

      DBus Specification Quote:

      Argument path matches provide a specialised form of wildcard matching for path-like namespaces. They can match arguments whose type is either STRING or OBJECT_PATH. As with normal argument matches, if the argument is exactly equal to the string given in the match rule then the rule is satisfied. Additionally, there is also a match when either the string given in the match rule or the appropriate message argument ends with '/' and is a prefix of the other. An example argument path match is arg0path='/aa/bb/'. This would match messages with first arguments of '/', '/aa/', '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.

      This is intended for monitoring “directories” in file system-like hierarchies, as used in the dconf configuration system. An application interested in all nodes in a particular hierarchy would monitor arg0path='/ca/example/foo/'. Then the service could emit a signal with zeroth argument "/ca/example/foo/bar" to represent a modification to the “bar” property, or a signal with zeroth argument "/ca/example/" to represent atomic modification of many properties within that directory, and the interested application would be notified in both cases.

      Parameters:
      _argId - argument number
      _arg0123Path - argument value to filter, null to remove
      Returns:
      this

    • withArg0Namespace

      public DBusMatchRuleBuilder withArg0Namespace(String _arg0Namespace)
      Set arg0Namespace filter.

      DBus Specification Quote:

      Match messages whose first argument is of type STRING, and is a bus name or interface name within the specified namespace. This is primarily intended for watching name owner changes for a group of related bus names, rather than for a single name or all name changes.

      Because every valid interface name is also a valid bus name, this can also be used for messages whose first argument is an interface name.

      For example, the match rule member='NameOwnerChanged',arg0namespace='com.example.backend1' matches name owner changes for bus names such as com.example.backend1.foo, com.example.backend1.foo.bar, and com.example.backend1 itself.

      Parameters:
      _arg0Namespace - to filter, null to remove
      Returns:
      this

    • withPathNamespace

      public DBusMatchRuleBuilder withPathNamespace(String _pathNamespace)
      Set path namespace filter.

      DBus Specification Quote:

      Matches messages which are sent from or to an object for which the object path is either the given value, or that value followed by one or more path components.

      For example, path_namespace='/com/example/foo' would match signals sent by /com/example/foo or by /com/example/foo/bar, but not by /com/example/foobar.

      Using both path and path_namespace in the same match rule is not allowed.

      Parameters:
      _pathNamespace - to filter, null to remove
      Returns:
      this
      Throws:
      IllegalArgumentException - when path already set

    • build

      public DBusMatchRule build()
      Create a new DBusMatchRule using the configured values of this builder.
      Returns:
      DBusMatchRule
      Throws:
      IllegalStateException - when no rule was defined

    • create

      public static DBusMatchRuleBuilder create()
      Creates a new builder instance.
      Returns:
      new instance