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 instance.
      Returns:
      Native handle

    • getTopic

      public Topic getTopic​(String name)
      Get (generic) topic.
      Parameters:
      name - topic name
      Returns:
      Topic

    • getBooleanTopic

      public BooleanTopic getBooleanTopic​(String name)
      Get boolean topic.
      Parameters:
      name - topic name
      Returns:
      BooleanTopic

    • getIntegerTopic

      public IntegerTopic getIntegerTopic​(String name)
      Get long topic.
      Parameters:
      name - topic name
      Returns:
      IntegerTopic

    • getFloatTopic

      public FloatTopic getFloatTopic​(String name)
      Get float topic.
      Parameters:
      name - topic name
      Returns:
      FloatTopic

    • getDoubleTopic

      public DoubleTopic getDoubleTopic​(String name)
      Get double topic.
      Parameters:
      name - topic name
      Returns:
      DoubleTopic

    • getStringTopic

      public StringTopic getStringTopic​(String name)
      Get String topic.
      Parameters:
      name - topic name
      Returns:
      StringTopic

    • getRawTopic

      public RawTopic getRawTopic​(String name)
      Get byte[] topic.
      Parameters:
      name - topic name
      Returns:
      RawTopic

    • getBooleanArrayTopic

      public BooleanArrayTopic getBooleanArrayTopic​(String name)
      Get boolean[] topic.
      Parameters:
      name - topic name
      Returns:
      BooleanArrayTopic

    • getIntegerArrayTopic

      public IntegerArrayTopic getIntegerArrayTopic​(String name)
      Get long[] topic.
      Parameters:
      name - topic name
      Returns:
      IntegerArrayTopic

    • getFloatArrayTopic

      public FloatArrayTopic getFloatArrayTopic​(String name)
      Get float[] topic.
      Parameters:
      name - topic name
      Returns:
      FloatArrayTopic

    • getDoubleArrayTopic

      public DoubleArrayTopic getDoubleArrayTopic​(String name)
      Get double[] topic.
      Parameters:
      name - topic name
      Returns:
      DoubleArrayTopic

    • getStringArrayTopic

      public StringArrayTopic getStringArrayTopic​(String name)
      Get String[] topic.
      Parameters:
      name - topic name
      Returns:
      StringArrayTopic

    • getProtobufTopic

      public <T,​ MessageType extends us.hebi.quickbuf.ProtoMessage<?>> ProtobufTopic<T> getProtobufTopic​(String name, Protobuf<T,​MessageType> proto)
      Get protobuf-encoded value topic.
      Type Parameters:
      T - value class (inferred from proto)
      MessageType - protobuf message type (inferred from proto)
      Parameters:
      name - topic name
      proto - protobuf serialization implementation
      Returns:
      ProtobufTopic

    • getStructTopic

      public <T> StructTopic<T> getStructTopic​(String name, Struct<T> struct)
      Get struct-encoded value topic.
      Type Parameters:
      T - value class (inferred from struct)
      Parameters:
      name - topic name
      struct - struct serialization implementation
      Returns:
      StructTopic

    • getStructArrayTopic

      public <T> StructArrayTopic<T> getStructArrayTopic​(String name, Struct<T> struct)
      Get struct-encoded value array topic.
      Type Parameters:
      T - value class (inferred from struct)
      Parameters:
      name - topic name
      struct - struct serialization implementation
      Returns:
      StructArrayTopic

    • getTopics

      public Topic[] getTopics()
      Get all published topics.
      Returns:
      Array of topics.

    • getTopics

      public Topic[] getTopics​(String prefix)
      Get published topics starting with the given prefix. The results are optionally filtered by string prefix to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      Returns:
      Array of topic information.

    • getTopics

      public Topic[] getTopics​(String prefix, int types)
      Get published topics starting with the given prefix. The results are optionally filtered by string prefix and data type to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      types - bitmask of data types; 0 is treated as a "don't care"
      Returns:
      Array of topic information.

    • getTopics

      public Topic[] getTopics​(String prefix, String[] types)
      Get published topics starting with the given prefix. The results are optionally filtered by string prefix and data type to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      types - array of data type strings
      Returns:
      Array of topic information.

    • getTopicInfo

      public TopicInfo[] getTopicInfo()
      Get information about all topics.
      Returns:
      Array of topic information.

    • getTopicInfo

      public TopicInfo[] getTopicInfo​(String prefix)
      Get information about topics starting with the given prefix. The results are optionally filtered by string prefix to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      Returns:
      Array of topic information.

    • getTopicInfo

      public TopicInfo[] getTopicInfo​(String prefix, int types)
      Get information about topics starting with the given prefix. The results are optionally filtered by string prefix and data type to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      types - bitmask of data types; 0 is treated as a "don't care"
      Returns:
      Array of topic information.

    • getTopicInfo

      public TopicInfo[] getTopicInfo​(String prefix, String[] types)
      Get information about topics starting with the given prefix. The results are optionally filtered by string prefix and data type to only return a subset of all topics.
      Parameters:
      prefix - topic name required prefix; only topics whose name starts with this string are returned
      types - array of data type strings
      Returns:
      Array of topic information.

    • getEntry

      public NetworkTableEntry getEntry​(String name)
      Gets the entry for a key.
      Parameters:
      name - Key
      Returns:
      Network table entry.

    • getTable

      public NetworkTable getTable​(String key)
      Gets the table with the specified key.
      Parameters:
      key - the key name
      Returns:
      The network table

    • removeListener

      public void removeListener​(int listener)
      Remove a connection listener.
      Parameters:
      listener - Listener handle to remove

    • waitForListenerQueue

      public boolean waitForListenerQueue​(double timeout)
      Wait for the listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the 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​(boolean immediateNotify, Consumer<NetworkTableEvent> listener)
      Add a connection listener. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function.
      Parameters:
      immediateNotify - Notify listener of all existing connections
      listener - Listener to add
      Returns:
      Listener handle

    • addTimeSyncListener

      public int addTimeSyncListener​(boolean immediateNotify, Consumer<NetworkTableEvent> listener)
      Add a time synchronization listener. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function.
      Parameters:
      immediateNotify - Notify listener of current time synchronization value
      listener - Listener to add
      Returns:
      Listener handle

    • addListener

      public int addListener​(Topic topic, EnumSet<NetworkTableEvent.Kind> eventKinds, Consumer<NetworkTableEvent> listener)
      Add a listener for changes on a particular topic. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function.

      This creates a corresponding internal subscriber with the lifetime of the listener.

      Parameters:
      topic - Topic
      eventKinds - set of event kinds to listen to
      listener - Listener function
      Returns:
      Listener handle

    • addListener

      public int addListener​(Subscriber subscriber, EnumSet<NetworkTableEvent.Kind> eventKinds, Consumer<NetworkTableEvent> listener)
      Add a listener for changes on a subscriber. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function. This does NOT keep the subscriber active.
      Parameters:
      subscriber - Subscriber
      eventKinds - set of event kinds to listen to
      listener - Listener function
      Returns:
      Listener handle

    • addListener

      public int addListener​(MultiSubscriber subscriber, EnumSet<NetworkTableEvent.Kind> eventKinds, Consumer<NetworkTableEvent> listener)
      Add a listener for changes on a subscriber. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function. This does NOT keep the subscriber active.
      Parameters:
      subscriber - Subscriber
      eventKinds - set of event kinds to listen to
      listener - Listener function
      Returns:
      Listener handle

    • addListener

      public int addListener​(NetworkTableEntry entry, EnumSet<NetworkTableEvent.Kind> eventKinds, Consumer<NetworkTableEvent> listener)
      Add a listener for changes on an entry. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function.
      Parameters:
      entry - Entry
      eventKinds - set of event kinds to listen to
      listener - Listener function
      Returns:
      Listener handle

    • addListener

      public int addListener​(String[] prefixes, EnumSet<NetworkTableEvent.Kind> eventKinds, Consumer<NetworkTableEvent> listener)
      Add a listener for changes to topics with names that start with any of the given prefixes. The callback function is called asynchronously on a separate thread, so it's important to use synchronization or atomics when accessing any shared state from the callback function.

      This creates a corresponding internal subscriber with the lifetime of the listener.

      Parameters:
      prefixes - Topic name string prefixes
      eventKinds - set of event kinds to listen to
      listener - Listener function
      Returns:
      Listener handle

    • getNetworkMode

      public EnumSet<NetworkTableInstance.NetworkMode> getNetworkMode()
      Get the current network mode.
      Returns:
      Enum set 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.json 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 port3)
      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
      port3 - port to communicate over (NT3)

    • startServer

      public void startServer​(String persistFilename, String listenAddress, int port3, int port4)
      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
      port3 - port to communicate over (NT3)
      port4 - port to communicate over (NT4)

    • stopServer

      public void stopServer()
      Stops the server if it is running.

    • startClient3

      public void startClient3​(String identity)
      Starts a NT3 client. Use SetServer or SetServerTeam to set the server name and port.
      Parameters:
      identity - network identity to advertise (cannot be empty string)

    • startClient4

      public void startClient4​(String identity)
      Starts a NT4 client. Use SetServer or SetServerTeam to set the server name and port.
      Parameters:
      identity - network identity to advertise (cannot be empty string)

    • 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 (0=default)

    • 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 (0=default)

    • 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 (0=default)

    • 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 (0=default)

    • disconnect

      public void disconnect()
      Disconnects the client if it's running and connected. This will automatically start reconnection attempts to the current server list.

    • 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 (0=default)

    • stopDSClient

      public void stopDSClient()
      Stops requesting server address from Driver Station.

    • flushLocal

      public void flushLocal()
      Flushes all updated values immediately to the local client/server. This does not flush to the network.

    • 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.

    • getServerTimeOffset

      public OptionalLong getServerTimeOffset()
      Get the time offset between server time and local time. Add this value to local time to get the estimated equivalent server time. In server mode, this always returns 0. In client mode, this returns the time offset only if the client and server are connected and have exchanged synchronization messages. Note the time offset may change over time as it is periodically updated; to receive updates as events, add a listener to the "time sync" event.
      Returns:
      Time offset in microseconds (optional)

    • startEntryDataLog

      public int startEntryDataLog​(DataLog log, String prefix, String logPrefix)
      Starts logging entry changes to a DataLog.
      Parameters:
      log - data log object; lifetime must extend until StopEntryDataLog is called or the instance is destroyed
      prefix - only store entries with names that start with this prefix; the prefix is not included in the data log entry name
      logPrefix - prefix to add to data log entry names
      Returns:
      Data logger handle

    • stopEntryDataLog

      public static void stopEntryDataLog​(int logger)
      Stops logging entry changes to a DataLog.
      Parameters:
      logger - data logger handle

    • startConnectionDataLog

      public int startConnectionDataLog​(DataLog log, String name)
      Starts logging connection changes to a DataLog.
      Parameters:
      log - data log object; lifetime must extend until StopConnectionDataLog is called or the instance is destroyed
      name - data log entry name
      Returns:
      Data logger handle

    • stopConnectionDataLog

      public static void stopConnectionDataLog​(int logger)
      Stops logging connection changes to a DataLog.
      Parameters:
      logger - data logger handle

    • addLogger

      public int addLogger​(int minLevel, int maxLevel, Consumer<NetworkTableEvent> func)
      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:
      minLevel - minimum log level
      maxLevel - maximum log level
      func - callback function
      Returns:
      Listener handle

    • hasSchema

      public boolean hasSchema​(String name)
      Returns whether there is a data schema already registered with the given name that this instance has published. This does NOT perform a check as to whether the schema has already been published by another node on the network.
      Parameters:
      name - Name (the string passed as the data type for topics using this schema)
      Returns:
      True if schema already registered

    • addSchema

      public void addSchema​(String name, String type, byte[] schema)
      Registers a data schema. Data schemas provide information for how a certain data type string can be decoded. The type string of a data schema indicates the type of the schema itself (e.g. "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In NetworkTables, schemas are published just like normal topics, with the name being generated from the provided name: "/.schema/name". Duplicate calls to this function with the same name are silently ignored.
      Parameters:
      name - Name (the string passed as the data type for topics using this schema)
      type - Type of schema (e.g. "protobuf", "struct", etc)
      schema - Schema data

    • addSchema

      public void addSchema​(String name, String type, String schema)
      Registers a data schema. Data schemas provide information for how a certain data type string can be decoded. The type string of a data schema indicates the type of the schema itself (e.g. "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In NetworkTables, schemas are published just like normal topics, with the name being generated from the provided name: "/.schema/name". Duplicate calls to this function with the same name are silently ignored.
      Parameters:
      name - Name (the string passed as the data type for topics using this schema)
      type - Type of schema (e.g. "protobuf", "struct", etc)
      schema - Schema data

    • addSchema

      public void addSchema​(Protobuf<?,​?> proto)
      Registers a protobuf schema. Duplicate calls to this function with the same name are silently ignored.
      Parameters:
      proto - protobuf serialization object

    • addSchema

      public void addSchema​(Struct<?> struct)
      Registers a struct schema. Duplicate calls to this function with the same name are silently ignored.
      Parameters:
      struct - struct serialization object

    • equals

      public boolean equals​(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object