com.digi.xbee.api

## Class XBeeNetwork

- java.lang.Object
- - com.digi.xbee.api.XBeeNetwork

- Direct Known Subclasses:
    DigiMeshNetwork, DigiPointNetwork, Raw802Network, ZigBeeNetwork

      public class XBeeNetwork
      extends Object

  This class represents an XBee Network.

  The network allows the discovery of remote devices in the same network as the local one and stores them.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDiscoveryListener(IDiscoveryListener listener)` Adds the given discovery listener to the list of listeners to be notified when the discovery process is running.
    `RemoteXBeeDevice` | `addRemoteDevice(RemoteXBeeDevice remoteDevice)` Adds a remote device to the network.
    `List<RemoteXBeeDevice>` | `addRemoteDevices(List<RemoteXBeeDevice> list)` Adds the given list of remote devices to the network.
    `void` | `clearDeviceList()` Removes all the devices from this network.
    `RemoteXBeeDevice` | `discoverDevice(String id)` Discovers and reports the first remote XBee device that matches the supplied identifier.
    `List<RemoteXBeeDevice>` | `discoverDevices(List<String> ids)` Discovers and reports all remote XBee devices that match the supplied identifiers.
    `RemoteXBeeDevice` | `getDevice(String id)` Returns the first remote device that matches the supplied identifier.
    `RemoteXBeeDevice` | `getDevice(XBee16BitAddress address)` Returns the remote device already contained in the network whose 16-bit address matches the given one.
    `RemoteXBeeDevice` | `getDevice(XBee64BitAddress address)` Returns the remote device already contained in the network whose 64-bit address matches the given one.
    `List<RemoteXBeeDevice>` | `getDevices()` Returns all remote devices already contained in the network.
    `List<RemoteXBeeDevice>` | `getDevices(String id)` Returns all remote devices that match the supplied identifier.
    `int` | `getNumberOfDevices()` Returns the number of devices already discovered in this network.
    `boolean` | `isDiscoveryRunning()` Retrieves whether the discovery process is running or not.
    `void` | `removeDiscoveryListener(IDiscoveryListener listener)` Removes the given discovery listener from the list of discovery listeners.
    `void` | `removeRemoteDevice(RemoteXBeeDevice remoteDevice)` Removes the given remote XBee device from the network.
    `void` | `setDiscoveryOptions(Set<DiscoveryOptions> options)` Configures the discovery options (`NO` parameter) with the given value.
    `void` | `setDiscoveryTimeout(long timeout)` Configures the discovery timeout (`NT` parameter) with the given value.
    `void` | `startDiscoveryProcess()` Starts the discovery process with the configured timeout and options.
    `void` | `stopDiscoveryProcess()` Stops the discovery process if it is running.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### addDiscoveryListener

          public void addDiscoveryListener(IDiscoveryListener listener)

      Adds the given discovery listener to the list of listeners to be notified when the discovery process is running.

      If the listener has already been included, this method does nothing.

      Parameters:
        `listener` - Listener to be notified when the discovery process is running.
      Throws:
        `NullPointerException` - if `listener == null`.
      See Also:
        `IDiscoveryListener`, `removeDiscoveryListener(IDiscoveryListener)`

    - #### addRemoteDevice

          public RemoteXBeeDevice addRemoteDevice(RemoteXBeeDevice remoteDevice)

      Adds a remote device to the network.

      This method will look for the 64-bit address. If it is not configured:

      - For 802.15.4 devices, it will look for the 16-bit address.
      - For the rest will return `false` as the result of the addition.
      Parameters:
        `remoteDevice` - The remote device to be added to the network.
      Returns:
        The remote XBee Device instance in the network, `null` if the device could not be successfully added.
      Throws:
        `NullPointerException` - if `RemoteDevice == null`.
      See Also:
        `addRemoteDevices(List)`

    - #### addRemoteDevices

          public List<RemoteXBeeDevice> addRemoteDevices(List<RemoteXBeeDevice> list)

      Adds the given list of remote devices to the network.

      The way of adding a device to the network is based on the 64-bit address. If it is not configured:

      - For 802.15.4 devices, the 16-bit address will be used instead.
      - For the rest will return `false` as the result of the addition.
      Parameters:
        `list` - The list of remote devices to be added to the network.
      Returns:
        A list with the successfully added devices to the network.
      Throws:
        `NullPointerException` - if `list == null`.
      See Also:
        `addRemoteDevice(RemoteXBeeDevice)`

    - #### clearDeviceList

          public void clearDeviceList()

      Removes all the devices from this network.

      The network will be empty after this call returns.

    - #### discoverDevice

          public RemoteXBeeDevice discoverDevice(String id)
                                          throws XBeeException

      Discovers and reports the first remote XBee device that matches the supplied identifier.

      This method blocks until the device is discovered or the configured timeout expires. To configure the discovery timeout, use the method `setDiscoveryTimeout(long)`.

      To configure the discovery options, use the `setDiscoveryOptions(Set)` method.

      Parameters:
        `id` - The identifier of the device to be discovered.
      Returns:
        The discovered remote XBee device with the given identifier, `null` if the timeout expires and the device was not found.
      Throws:
        `IllegalArgumentException` - if `id.length() == 0`.
        `InterfaceNotOpenException` - if the device is not open.
        `NullPointerException` - if `id == null`.
        `XBeeException` - if there is an error discovering the device.
      See Also:
        `discoverDevices(List)`, `getDevice(String)`, `RemoteXBeeDevice`

    - #### discoverDevices

          public List<RemoteXBeeDevice> discoverDevices(List<String> ids)
                                                 throws XBeeException

      Discovers and reports all remote XBee devices that match the supplied identifiers.

      This method blocks until the configured timeout expires. To configure the discovery timeout, use the method `setDiscoveryTimeout(long)`.

      To configure the discovery options, use the `setDiscoveryOptions(Set)` method.

      Parameters:
        `ids` - List which contains the identifiers of the devices to be discovered.
      Returns:
        A list of the discovered remote XBee devices with the given identifiers.
      Throws:
        `IllegalArgumentException` - if `ids.size() == 0`.
        `InterfaceNotOpenException` - if the device is not open.
        `NullPointerException` - if `ids == null`.
        `XBeeException` - if there is an error discovering the devices.
      See Also:
        `discoverDevice(String)`, `RemoteXBeeDevice`

    - #### getDevice

          public RemoteXBeeDevice getDevice(String id)

      Returns the first remote device that matches the supplied identifier.

      Note that this method does not perform a discovery, only returns the device that has been previously discovered.

      Parameters:
        `id` - The identifier of the device to be retrieved.
      Returns:
        The remote XBee device contained in the network with the given identifier, `null` if the network does not contain any device with that Node ID.
      Throws:
        `IllegalArgumentException` - if `id.length() == 0`.
        `NullPointerException` - if `id == null`.
      See Also:
        `discoverDevice(String)`, `getDevices(String)`, `RemoteXBeeDevice`

    - #### getDevice

          public RemoteXBeeDevice getDevice(XBee16BitAddress address)
                                     throws OperationNotSupportedException

      Returns the remote device already contained in the network whose 16-bit address matches the given one.

      Note that this method does not perform a discovery, only returns the device that has been previously discovered.

      Parameters:
        `address` - The 16-bit address of the device to be retrieved.
      Returns:
        The remote device in the network or `null` if it is not found.
      Throws:
        `IllegalArgumentException` - if `address.equals(XBee16BitAddress.UNKNOWN_ADDRESS)`.
        `NullPointerException` - if `address == null`.
        `OperationNotSupportedException` - if the protocol of the local XBee device is DigiMesh.

    - #### getDevice

          public RemoteXBeeDevice getDevice(XBee64BitAddress address)

      Returns the remote device already contained in the network whose 64-bit address matches the given one.

      Note that this method does not perform a discovery, only returns the device that has been previously discovered.

      Parameters:
        `address` - The 64-bit address of the device to be retrieved.
      Returns:
        The remote device in the network or `null` if it is not found.
      Throws:
        `IllegalArgumentException` - if `address.equals(XBee64BitAddress.UNKNOWN_ADDRESS)`.
        `NullPointerException` - if `address == null`.

    - #### getDevices

          public List<RemoteXBeeDevice> getDevices()

      Returns all remote devices already contained in the network.

      Note that this method does not perform a discovery, only returns the devices that have been previously discovered.

      Returns:
        A list with all XBee devices in the network.
      See Also:
        `getDevices(String)`, `RemoteXBeeDevice`

    - #### getDevices

          public List<RemoteXBeeDevice> getDevices(String id)

      Returns all remote devices that match the supplied identifier.

      Note that this method does not perform a discovery, only returns the devices that have been previously discovered.

      Parameters:
        `id` - The identifier of the devices to be retrieved.
      Returns:
        A list of the remote XBee devices contained in the network with the given identifier.
      Throws:
        `IllegalArgumentException` - if `id.length() == 0`.
        `NullPointerException` - if `id == null`.
      See Also:
        `getDevice(String)`, `RemoteXBeeDevice`

    - #### getNumberOfDevices

          public int getNumberOfDevices()

      Returns the number of devices already discovered in this network.
      Returns:
        The number of devices already discovered in this network.

    - #### isDiscoveryRunning

          public boolean isDiscoveryRunning()

      Retrieves whether the discovery process is running or not.
      Returns:
        `true` if the discovery process is running, `false` otherwise.
      See Also:
        `startDiscoveryProcess()`, `stopDiscoveryProcess()`

    - #### removeDiscoveryListener

          public void removeDiscoveryListener(IDiscoveryListener listener)

      Removes the given discovery listener from the list of discovery listeners.

      If the listener is not included in the list, this method does nothing.

      Parameters:
        `listener` - Discovery listener to remove.
      Throws:
        `NullPointerException` - if `listener == null`.
      See Also:
        `IDiscoveryListener`, `addDiscoveryListener(IDiscoveryListener)`

    - #### removeRemoteDevice

          public void removeRemoteDevice(RemoteXBeeDevice remoteDevice)

      Removes the given remote XBee device from the network.

      This method will check for a device that matches the 64-bit address of the provided one, if found, that device will be removed from the corresponding list. In case the 64-bit address is null, it will look for the device in the 16-bit addresses list.

      Parameters:
        `remoteDevice` - The remote device to be removed from the network.
      Throws:
        `NullPointerException` - if `RemoteDevice == null`.

    - #### setDiscoveryOptions

          public void setDiscoveryOptions(Set<DiscoveryOptions> options)
                                   throws TimeoutException,
                                          XBeeException

      Configures the discovery options (`NO` parameter) with the given value.
      Parameters:
        `options` - New discovery options.
      Throws:
        `TimeoutException` - if there is a timeout setting the discovery options.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `setDiscoveryTimeout(long)`

    - #### setDiscoveryTimeout

          public void setDiscoveryTimeout(long timeout)
                                   throws TimeoutException,
                                          XBeeException

      Configures the discovery timeout (`NT` parameter) with the given value.

      Note that in some protocols, the discovery process may take longer than the value set in this method due to the network propagation time.

      Parameters:
        `timeout` - New discovery timeout in milliseconds.
      Throws:
        `TimeoutException` - if there is a timeout setting the discovery timeout.
        `XBeeException` - if there is any other XBee related exception.
      See Also:
        `setDiscoveryOptions(Set)`

    - #### startDiscoveryProcess

          public void startDiscoveryProcess()

      Starts the discovery process with the configured timeout and options.

      To be notified every time an XBee device is discovered, add a `IDiscoveryListener` using the `addDiscoveryListener(IDiscoveryListener)` method before starting the discovery process.

      To configure the discovery timeout, use the `setDiscoveryTimeout(long)` method.

      To configure the discovery options, use the `setDiscoveryOptions(Set)` method.

      Throws:
        `IllegalStateException` - if the discovery process is already running.
        `InterfaceNotOpenException` - if the device is not open.
      See Also:
        `addDiscoveryListener(IDiscoveryListener)`, `stopDiscoveryProcess()`

    - #### stopDiscoveryProcess

          public void stopDiscoveryProcess()

      Stops the discovery process if it is running.

      Note that DigiMesh/DigiPoint devices are blocked until the discovery time configured (NT parameter) has elapsed, so if you try to get/set any parameter during the discovery process you will receive a timeout exception.

      See Also:
        `isDiscoveryRunning()`, `removeDiscoveryListener(IDiscoveryListener)`, `startDiscoveryProcess()`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

© Copyright 2014–2014 Digi International Inc. All rights reserved.