edu.wpi.first.networktables

## Class NetworkTableInstance

- java.lang.Object
- - edu.wpi.first.networktables.NetworkTableInstance

-     public final class NetworkTableInstance
      extends java.lang.Object

  NetworkTables Instance. Instances are completely independent from each other. Table operations on one instance will not be visible to other instances unless the instances are connected via the network. The main limitation on instances is that you cannot have two servers on the same network port. The main utility of instances is for unit testing, but they can also enable one program to connect to two different NetworkTables networks. The global "default" instance (as returned by `getDefault()`) is always available, and is intended for the common case when there is only a single NetworkTables instance being used in the program. Additional instances can be created with the `create()` function. A reference must be kept to the NetworkTableInstance returned by this function to keep it from being garbage collected.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `kDefaultPort` The default port that network tables operates on.
    `static int` | `kNetModeClient`
    `static int` | `kNetModeFailure`
    `static int` | `kNetModeNone` Client/server mode flag values (as returned by `getNetworkMode()`).
    `static int` | `kNetModeServer`
    `static int` | `kNetModeStarting`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `addConnectionListener(java.util.function.Consumer<ConnectionNotification> listener, boolean immediateNotify)` Add a connection listener.
    `int` | `addEntryListener(NetworkTableEntry entry, java.util.function.Consumer<EntryNotification> listener, int flags)` Add a listener for a particular entry.
    `int` | `addEntryListener(java.lang.String prefix, java.util.function.Consumer<EntryNotification> listener, int flags)` Add a listener for all entries starting with a certain prefix.
    `int` | `addLogger(java.util.function.Consumer<LogMessage> func, int minLevel, int maxLevel)` Add logger callback function.
    `static NetworkTableInstance` | `create()` Create an instance.
    `void` | `createRpc(NetworkTableEntry entry, java.util.function.Consumer<RpcAnswer> callback)` Create a callback-based RPC entry point.
    `void` | `deleteAllEntries()` Deletes ALL keys in ALL subtables (except persistent values).
    `boolean` | `equals(java.lang.Object o)`
    `void` | `flush()` Flushes all updated values immediately to the network.
    `void` | `free()` Destroys the instance (if created by `create()`).
    `ConnectionInfo[]` | `getConnections()` Gets information on the currently established network connections.
    `static NetworkTableInstance` | `getDefault()` Get global default instance.
    `NetworkTableEntry[]` | `getEntries(java.lang.String prefix, int types)` Get entries starting with the given prefix.
    `NetworkTableEntry` | `getEntry(java.lang.String name)` Gets the entry for a key.
    `EntryInfo[]` | `getEntryInfo(java.lang.String prefix, int types)` Get information about entries starting with the given prefix.
    `int` | `getHandle()` Gets the native handle for the entry.
    `int` | `getNetworkMode()` Get the current network mode.
    `NetworkTable` | `getTable(java.lang.String key)` Gets the table with the specified key.
    `int` | `hashCode()`
    `boolean` | `isConnected()` Return whether or not the instance is connected to another node.
    `boolean` | `isValid()` Determines if the native handle is valid.
    `java.lang.String[]` | `loadEntries(java.lang.String filename, java.lang.String prefix)` Load table values from a file.
    `java.lang.String[]` | `loadPersistent(java.lang.String filename)` Loads persistent keys from a file.
    `void` | `removeConnectionListener(int listener)` Remove a connection listener.
    `void` | `removeEntryListener(int listener)` Remove an entry listener.
    `void` | `removeLogger(int logger)` Remove a logger.
    `void` | `saveEntries(java.lang.String filename, java.lang.String prefix)` Save table values to a file.
    `void` | `savePersistent(java.lang.String filename)` Saves persistent keys to a file.
    `void` | `setNetworkIdentity(java.lang.String name)` Set the network identity of this node.
    `void` | `setServer(java.lang.String serverName)` Sets server address and port for client (without restarting client).
    `void` | `setServer(java.lang.String[] serverNames)` Sets server addresses and port for client (without restarting client).
    `void` | `setServer(java.lang.String[] serverNames, int port)` Sets server addresses and port for client (without restarting client).
    `void` | `setServer(java.lang.String[] serverNames, int[] ports)` Sets server addresses and ports for client (without restarting client).
    `void` | `setServer(java.lang.String serverName, int port)` Sets server address and port for client (without restarting client).
    `void` | `setServerTeam(int team)` Sets server addresses and port for client (without restarting client).
    `void` | `setServerTeam(int team, int port)` Sets server addresses and port for client (without restarting client).
    `void` | `setUpdateRate(double interval)` Set the periodic update rate.
    `void` | `startClient()` Starts a client.
    `void` | `startClient(java.lang.String serverName)` Starts a client using the specified server and the default port
    `void` | `startClient(java.lang.String[] serverNames)` Starts a client using the specified servers and default port.
    `void` | `startClient(java.lang.String[] serverNames, int port)` Starts a client using the specified servers and port number.
    `void` | `startClient(java.lang.String[] serverNames, int[] ports)` Starts a client using the specified (server, port) combinations.
    `void` | `startClient(java.lang.String serverName, int port)` Starts a client using the specified server and port
    `void` | `startClientTeam(int team)` Starts a client using commonly known robot addresses for the specified team using the default port number.
    `void` | `startClientTeam(int team, int port)` Starts a client using commonly known robot addresses for the specified team.
    `void` | `startDSClient()` Starts requesting server address from Driver Station.
    `void` | `startDSClient(int port)` Starts requesting server address from Driver Station.
    `void` | `startServer()` Starts a server using the networktables.ini as the persistent file, using the default listening address and port.
    `void` | `startServer(java.lang.String persistFilename)` Starts a server using the specified persistent filename, using the default listening address and port.
    `void` | `startServer(java.lang.String persistFilename, java.lang.String listenAddress)` Starts a server using the specified filename and listening address, using the default port.
    `void` | `startServer(java.lang.String persistFilename, java.lang.String listenAddress, int port)` Starts a server using the specified filename, listening address, and port.
    `void` | `stopClient()` Stops the client if it is running.
    `void` | `stopDSClient()` Stops requesting server address from Driver Station.
    `void` | `stopServer()` Stops the server if it is running.
    `boolean` | `waitForConnectionListenerQueue(double timeout)` Wait for the connection listener queue to be empty.
    `boolean` | `waitForEntryListenerQueue(double timeout)` Wait for the entry listener queue to be empty.
    `boolean` | `waitForLoggerQueue(double timeout)` Wait for the incoming log event queue to be empty.
    `boolean` | `waitForRpcCallQueue(double timeout)` Wait for the incoming RPC call queue to be empty.

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

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### kNetModeNone

          public static final int kNetModeNone

      Client/server mode flag values (as returned by `getNetworkMode()`). This is a bitmask.
      See Also:
        Constant Field Values

    - #### kNetModeServer

          public static final int kNetModeServer

      See Also:
        Constant Field Values

    - #### kNetModeClient

          public static final int kNetModeClient

      See Also:
        Constant Field Values

    - #### kNetModeStarting

          public static final int kNetModeStarting

      See Also:
        Constant Field Values

    - #### kNetModeFailure

          public static final int kNetModeFailure

      See Also:
        Constant Field Values

    - #### kDefaultPort

          public static final int kDefaultPort

      The default port that network tables operates on.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### free

          public void free()

      Destroys the instance (if created by `create()`).

    - #### isValid

          public boolean isValid()

      Determines if the native handle is valid.
      Returns:
        True if the native handle is valid, false otherwise.

    - #### getDefault

          public static NetworkTableInstance getDefault()

      Get global default instance.
      Returns:
        Global default instance

    - #### create

          public static NetworkTableInstance create()

      Create an instance. Note: A reference to the returned instance must be retained to ensure the instance is not garbage collected.
      Returns:
        Newly created instance

    - #### getHandle

          public int getHandle()

      Gets the native handle for the entry.
      Returns:
        Native handle

    - #### getEntry

          public NetworkTableEntry getEntry(java.lang.String name)

      Gets the entry for a key.
      Parameters:
        `name` - Key
      Returns:
        Network table entry.

    - #### getEntries

          public NetworkTableEntry[] getEntries(java.lang.String prefix,
                                                int types)

      Get entries starting with the given prefix. The results are optionally filtered by string prefix and entry type to only return a subset of all entries.
      Parameters:
        `prefix` - entry name required prefix; only entries whose name starts with this string are returned
        `types` - bitmask of types; 0 is treated as a "don't care"
      Returns:
        Array of entries.

    - #### getEntryInfo

          public EntryInfo[] getEntryInfo(java.lang.String prefix,
                                          int types)

      Get information about entries starting with the given prefix. The results are optionally filtered by string prefix and entry type to only return a subset of all entries.
      Parameters:
        `prefix` - entry name required prefix; only entries whose name starts with this string are returned
        `types` - bitmask of types; 0 is treated as a "don't care"
      Returns:
        Array of entry information.

    - #### getTable

          public NetworkTable getTable(java.lang.String key)

      Gets the table with the specified key.
      Parameters:
        `key` - the key name
      Returns:
        The network table

    - #### deleteAllEntries

          public void deleteAllEntries()

      Deletes ALL keys in ALL subtables (except persistent values). Use with caution!

    - #### addEntryListener

          public int addEntryListener(java.lang.String prefix,
                                      java.util.function.Consumer<EntryNotification> listener,
                                      int flags)

      Add a listener for all entries starting with a certain prefix.
      Parameters:
        `prefix` - UTF-8 string prefix
        `listener` - listener to add
        `flags` - `EntryListenerFlags` bitmask
      Returns:
        Listener handle

    - #### addEntryListener

          public int addEntryListener(NetworkTableEntry entry,
                                      java.util.function.Consumer<EntryNotification> listener,
                                      int flags)

      Add a listener for a particular entry.
      Parameters:
        `entry` - the entry
        `listener` - listener to add
        `flags` - `EntryListenerFlags` bitmask
      Returns:
        Listener handle

    - #### removeEntryListener

          public void removeEntryListener(int listener)

      Remove an entry listener.
      Parameters:
        `listener` - Listener handle to remove

    - #### waitForEntryListenerQueue

          public boolean waitForEntryListenerQueue(double timeout)

      Wait for the entry listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the entry listener queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.
      Parameters:
        `timeout` - timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
      Returns:
        False if timed out, otherwise true.

    - #### addConnectionListener

          public int addConnectionListener(java.util.function.Consumer<ConnectionNotification> listener,
                                           boolean immediateNotify)

      Add a connection listener.
      Parameters:
        `listener` - Listener to add
        `immediateNotify` - Notify listener of all existing connections
      Returns:
        Listener handle

    - #### removeConnectionListener

          public void removeConnectionListener(int listener)

      Remove a connection listener.
      Parameters:
        `listener` - Listener handle to remove

    - #### waitForConnectionListenerQueue

          public boolean waitForConnectionListenerQueue(double timeout)

      Wait for the connection listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the connection listener queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.
      Parameters:
        `timeout` - timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
      Returns:
        False if timed out, otherwise true.

    - #### createRpc

          public void createRpc(NetworkTableEntry entry,
                                java.util.function.Consumer<RpcAnswer> callback)

      Create a callback-based RPC entry point. Only valid to use on the server. The callback function will be called when the RPC is called. This function creates RPC version 0 definitions (raw data in and out).
      Parameters:
        `entry` - the entry
        `callback` - callback function

    - #### waitForRpcCallQueue

          public boolean waitForRpcCallQueue(double timeout)

      Wait for the incoming RPC call queue to be empty. This is primarily useful for deterministic testing. This blocks until either the RPC call queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.
      Parameters:
        `timeout` - timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
      Returns:
        False if timed out, otherwise true.

    - #### setNetworkIdentity

          public void setNetworkIdentity(java.lang.String name)

      Set the network identity of this node. This is the name used during the initial connection handshake, and is visible through ConnectionInfo on the remote node.
      Parameters:
        `name` - identity to advertise

    - #### getNetworkMode

          public int getNetworkMode()

      Get the current network mode.
      Returns:
        Bitmask of NetworkMode.

    - #### startServer

          public void startServer()

      Starts a server using the networktables.ini as the persistent file, using the default listening address and port.

    - #### startServer

          public void startServer(java.lang.String persistFilename)

      Starts a server using the specified persistent filename, using the default listening address and port.
      Parameters:
        `persistFilename` - the name of the persist file to use

    - #### startServer

          public void startServer(java.lang.String persistFilename,
                                  java.lang.String listenAddress)

      Starts a server using the specified filename and listening address, using the default port.
      Parameters:
        `persistFilename` - the name of the persist file to use
        `listenAddress` - the address to listen on, or empty to listen on any address

    - #### startServer

          public void startServer(java.lang.String persistFilename,
                                  java.lang.String listenAddress,
                                  int port)

      Starts a server using the specified filename, listening address, and port.
      Parameters:
        `persistFilename` - the name of the persist file to use
        `listenAddress` - the address to listen on, or empty to listen on any address
        `port` - port to communicate over

    - #### stopServer

          public void stopServer()

      Stops the server if it is running.

    - #### startClient

          public void startClient()

      Starts a client. Use SetServer to set the server name and port.

    - #### startClient

          public void startClient(java.lang.String serverName)

      Starts a client using the specified server and the default port
      Parameters:
        `serverName` - server name

    - #### startClient

          public void startClient(java.lang.String serverName,
                                  int port)

      Starts a client using the specified server and port
      Parameters:
        `serverName` - server name
        `port` - port to communicate over

    - #### startClient

          public void startClient(java.lang.String[] serverNames)

      Starts a client using the specified servers and default port. The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names

    - #### startClient

          public void startClient(java.lang.String[] serverNames,
                                  int port)

      Starts a client using the specified servers and port number. The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names
        `port` - port to communicate over

    - #### startClient

          public void startClient(java.lang.String[] serverNames,
                                  int[] ports)

      Starts a client using the specified (server, port) combinations. The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names
        `ports` - array of port numbers

    - #### startClientTeam

          public void startClientTeam(int team)

      Starts a client using commonly known robot addresses for the specified team using the default port number.
      Parameters:
        `team` - team number

    - #### startClientTeam

          public void startClientTeam(int team,
                                      int port)

      Starts a client using commonly known robot addresses for the specified team.
      Parameters:
        `team` - team number
        `port` - port to communicate over

    - #### stopClient

          public void stopClient()

      Stops the client if it is running.

    - #### setServer

          public void setServer(java.lang.String serverName)

      Sets server address and port for client (without restarting client). Changes the port to the default port.
      Parameters:
        `serverName` - server name

    - #### setServer

          public void setServer(java.lang.String serverName,
                                int port)

      Sets server address and port for client (without restarting client).
      Parameters:
        `serverName` - server name
        `port` - port to communicate over

    - #### setServer

          public void setServer(java.lang.String[] serverNames)

      Sets server addresses and port for client (without restarting client). Changes the port to the default port. The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names

    - #### setServer

          public void setServer(java.lang.String[] serverNames,
                                int port)

      Sets server addresses and port for client (without restarting client). The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names
        `port` - port to communicate over

    - #### setServer

          public void setServer(java.lang.String[] serverNames,
                                int[] ports)

      Sets server addresses and ports for client (without restarting client). The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `serverNames` - array of server names
        `ports` - array of port numbers

    - #### setServerTeam

          public void setServerTeam(int team)

      Sets server addresses and port for client (without restarting client). Changes the port to the default port. The client will attempt to connect to each server in round robin fashion.
      Parameters:
        `team` - team number

    - #### setServerTeam

          public void setServerTeam(int team,
                                    int port)

      Sets server addresses and port for client (without restarting client). Connects using commonly known robot addresses for the specified team.
      Parameters:
        `team` - team number
        `port` - port to communicate over

    - #### startDSClient

          public void startDSClient()

      Starts requesting server address from Driver Station. This connects to the Driver Station running on localhost to obtain the server IP address, and connects with the default port.

    - #### startDSClient

          public void startDSClient(int port)

      Starts requesting server address from Driver Station. This connects to the Driver Station running on localhost to obtain the server IP address.
      Parameters:
        `port` - server port to use in combination with IP from DS

    - #### stopDSClient

          public void stopDSClient()

      Stops requesting server address from Driver Station.

    - #### setUpdateRate

          public void setUpdateRate(double interval)

      Set the periodic update rate. Sets how frequently updates are sent to other nodes over the network.
      Parameters:
        `interval` - update interval in seconds (range 0.01 to 1.0)

    - #### flush

          public void flush()

      Flushes all updated values immediately to the network. Note: This is rate-limited to protect the network from flooding. This is primarily useful for synchronizing network updates with user code.

    - #### getConnections

          public ConnectionInfo[] getConnections()

      Gets information on the currently established network connections. If operating as a client, this will return either zero or one values.
      Returns:
        array of connection information

    - #### isConnected

          public boolean isConnected()

      Return whether or not the instance is connected to another node.
      Returns:
        True if connected.

    - #### savePersistent

          public void savePersistent(java.lang.String filename)
                              throws PersistentException

      Saves persistent keys to a file. The server does this automatically.
      Parameters:
        `filename` - file name
      Throws:
        `PersistentException` - if error saving file

    - #### loadPersistent

          public java.lang.String[] loadPersistent(java.lang.String filename)
                                            throws PersistentException

      Loads persistent keys from a file. The server does this automatically.
      Parameters:
        `filename` - file name
      Returns:
        List of warnings (errors result in an exception instead)
      Throws:
        `PersistentException` - if error reading file

    - #### saveEntries

          public void saveEntries(java.lang.String filename,
                                  java.lang.String prefix)
                           throws PersistentException

      Save table values to a file. The file format used is identical to that used for SavePersistent.
      Parameters:
        `filename` - filename
        `prefix` - save only keys starting with this prefix
      Throws:
        `PersistentException` - if error saving file

    - #### loadEntries

          public java.lang.String[] loadEntries(java.lang.String filename,
                                                java.lang.String prefix)
                                         throws PersistentException

      Load table values from a file. The file format used is identical to that used for SavePersistent / LoadPersistent.
      Parameters:
        `filename` - filename
        `prefix` - load only keys starting with this prefix
      Returns:
        List of warnings (errors result in an exception instead)
      Throws:
        `PersistentException` - if error saving file

    - #### addLogger

          public int addLogger(java.util.function.Consumer<LogMessage> func,
                               int minLevel,
                               int maxLevel)

      Add logger callback function. By default, log messages are sent to stderr; this function sends log messages with the specified levels to the provided callback function instead. The callback function will only be called for log messages with level greater than or equal to minLevel and less than or equal to maxLevel; messages outside this range will be silently ignored.
      Parameters:
        `func` - log callback function
        `minLevel` - minimum log level
        `maxLevel` - maximum log level
      Returns:
        Logger handle

    - #### removeLogger

          public void removeLogger(int logger)

      Remove a logger.
      Parameters:
        `logger` - Logger handle to remove

    - #### waitForLoggerQueue

          public boolean waitForLoggerQueue(double timeout)

      Wait for the incoming log event queue to be empty. This is primarily useful for deterministic testing. This blocks until either the log event queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.
      Parameters:
        `timeout` - timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
      Returns:
        False if timed out, otherwise true.

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`