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

    • Method Detail

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

        public int hashCode()
        Overrides:
        hashCode in class Object