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     public 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     public @Nullable DiscoveryResult createResult(BluetoothDiscoveryDevice device);
  50
  51     /**
  52      * Returns the thing UID for a Bluetooth device
  53      *
  54      * @param device the Bluetooth device
  55      * @return a thing UID or <code>null</code>, if the device is not supported by this participant
  56      */
  57     public @Nullable ThingUID getThingUID(BluetoothDiscoveryDevice device);
  58
  59     /**
  60      * Returns true if this participant requires the device to be connected before it can produce a
  61      * DiscoveryResult (or null) from {@link createResult(BluetoothDevice)}.
  62      * <p>
  63      * Implementors should only return 'true' conservatively, and make sure to return 'false' in circumstances where a
  64      * 'null' result would be guaranteed from {@link createResult(BluetoothDevice)} even if a connection was available
  65      * (e.g. the advertised manufacturerId already mismatches).
  66      * <p>
  67      * In general, returning 'true' is equivalent to saying <i>"the device might match, but I need a connection to
  68      * make sure"</i>.
  69      *
  70      * @param device the Bluetooth device
  71      * @return true if a connection is required before calling {@link createResult(BluetoothDevice)}
  72      */
  73     public default boolean requiresConnection(BluetoothDiscoveryDevice device) {
  74         return false;
  75     }
  76
  77     /**
  78      * Allows participants to perform any post-processing on each DiscoveryResult as well
  79      * as produce additional DiscoveryResults as they see fit.
  80      * Additional results can be published using the provided {@code publisher}.
  81      * Results published in this way will create a new DiscoveryResult and ThingUID
  82      * using the provided {@link BluetoothAdapter} as the bridge instead.
  83      * A BluetoothAdapter instance must be provided for any additional results sent to the publisher.
  84      * <p>
  85      * Note: Any additional results will not be subject to post-processing.
  86      *
  87      * @param result the DiscoveryResult to post-process
  88      * @param publisher the consumer to publish additional results to.
  89      */
  90     public default void publishAdditionalResults(DiscoveryResult result,
  91             BiConsumer<BluetoothAdapter, DiscoveryResult> publisher) {
  92         // do nothing by default
  93     }
  94
  95     /**
  96      * Overriding this method allows discovery participants to dictate the order in which they should be evaluated
  97      * relative to other discovery participants. Participants with a lower order value are evaluated first.
  98      *
  99      * @return the order of this participant, default 0
 100      */
 101     public default int order() {
 102         return 0;
 103     }
 104 }