Package edu.wpi.first.networktables

Class NetworkTableInstance

java.lang.Object
edu.wpi.first.networktables.NetworkTableInstance
All Implemented Interfaces:
AutoCloseable
public final class NetworkTableInstance
extends Object
implements AutoCloseable
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 Details

  • Method Details

    • close

      public void close()
      Destroys the instance (if created by create()).
      Specified by:
      close in interface AutoCloseable

    • 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​(String name)
      Gets the entry for a key.
      Parameters:
      name - Key
      Returns:
      Network table entry.

    • getEntries

      public NetworkTableEntry[] getEntries​(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​(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​(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​(String prefix, 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, 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​(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, 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​(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.

    • startLocal

      public void startLocal()
      Starts local-only operation. Prevents calls to startServer or startClient from taking effect. Has no effect if startServer or startClient has already been called.

    • stopLocal

      public void stopLocal()
      Stops local-only operation. startServer or startClient can be called after this call to start a server or client.

    • 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​(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​(String persistFilename, 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​(String persistFilename, 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​(String serverName)
      Starts a client using the specified server and the default port.
      Parameters:
      serverName - server name

    • startClient

      public void startClient​(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​(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​(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​(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​(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​(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​(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​(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​(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​(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 String[] loadPersistent​(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​(String filename, 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 String[] loadEntries​(String filename, 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​(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​(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object