git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.bluetooth.discovery;
  14
  15 import java.util.Set;
  16 import java.util.function.BiConsumer;
  17
  18 import org.eclipse.jdt.annotation.NonNullByDefault;
  19 import org.eclipse.jdt.annotation.Nullable;
  20 import org.openhab.binding.bluetooth.BluetoothAdapter;
  21 import org.openhab.core.config.discovery.DiscoveryResult;
  22 import org.openhab.core.thing.ThingTypeUID;
  23 import org.openhab.core.thing.ThingUID;
  24
  25 /**
  26  * A {@link BluetoothDiscoveryParticipant} that is registered as a service is picked up by the BluetoothDiscoveryService
  27  * and can thus contribute {@link DiscoveryResult}s from Bluetooth scans.
  28  *
  29  * @author Kai Kreuzer - Initial contribution
  30  * @author Connor Petty - added 'requiresConnection' and 'publishAdditionalResults' methods
  31  */
  32 @NonNullByDefault
  33 public interface BluetoothDiscoveryParticipant {
  34
  35     /**
  36      * Defines the list of thing types that this participant can identify
  37      *
  38      * @return a set of thing type UIDs for which results can be created
  39      */
  40     Set<ThingTypeUID> getSupportedThingTypeUIDs();
  41
  42     /**
  43      * Creates a discovery result for a Bluetooth device
  44      *
  45      * @param device the Bluetooth device found on the network
  46      * @return the according discovery result or <code>null</code>, if device is not
  47      *         supported by this participant
  48      */
  49     @Nullable
  50     DiscoveryResult createResult(BluetoothDiscoveryDevice device);
  51
  52     /**
  53      * Returns the thing UID for a Bluetooth device
  54      *
  55      * @param device the Bluetooth device
  56      * @return a thing UID or <code>null</code>, if the device is not supported by this participant
  57      */
  58     @Nullable
  59     ThingUID getThingUID(BluetoothDiscoveryDevice device);
  60
  61     /**
  62      * Returns true if this participant requires the device to be connected before it can produce a
  63      * DiscoveryResult (or null) from {@link createResult(BluetoothDevice)}.
  64      * <p>
  65      * Implementors should only return 'true' conservatively, and make sure to return 'false' in circumstances where a
  66      * 'null' result would be guaranteed from {@link createResult(BluetoothDevice)} even if a connection was available
  67      * (e.g. the advertised manufacturerId already mismatches).
  68      * <p>
  69      * In general, returning 'true' is equivalent to saying <i>"the device might match, but I need a connection to
  70      * make sure"</i>.
  71      *
  72      * @param device the Bluetooth device
  73      * @return true if a connection is required before calling {@link createResult(BluetoothDevice)}
  74      */
  75     default boolean requiresConnection(BluetoothDiscoveryDevice device) {
  76         return false;
  77     }
  78
  79     /**
  80      * Allows participants to perform any post-processing on each DiscoveryResult as well
  81      * as produce additional DiscoveryResults as they see fit.
  82      * Additional results can be published using the provided {@code publisher}.
  83      * Results published in this way will create a new DiscoveryResult and ThingUID
  84      * using the provided {@link BluetoothAdapter} as the bridge instead.
  85      * A BluetoothAdapter instance must be provided for any additional results sent to the publisher.
  86      * <p>
  87      * Note: Any additional results will not be subject to post-processing.
  88      *
  89      * @param result the DiscoveryResult to post-process
  90      * @param publisher the consumer to publish additional results to.
  91      */
  92     default void publishAdditionalResults(DiscoveryResult result,
  93             BiConsumer<BluetoothAdapter, DiscoveryResult> publisher) {
  94         // do nothing by default
  95     }
  96
  97     /**
  98      * Overriding this method allows discovery participants to dictate the order in which they should be evaluated
  99      * relative to other discovery participants. Participants with a lower order value are evaluated first.
 100      *
 101      * @return the order of this participant, default 0
 102      */
 103     default int order() {
 104         return 0;
 105     }
 106 }