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 Summary
Fields Modifier and Type Field Description static int
kDefaultPort
The default port that network tables operates on.static int
kNetModeClient
static int
kNetModeFailure
static int
kNetModeLocal
static int
kNetModeNone
Client/server mode flag values (as returned bygetNetworkMode()
).static int
kNetModeServer
static int
kNetModeStarting
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
addConnectionListener(Consumer<ConnectionNotification> listener, boolean immediateNotify)
Add a connection listener.int
addEntryListener(NetworkTableEntry entry, Consumer<EntryNotification> listener, int flags)
Add a listener for a particular entry.int
addEntryListener(String prefix, Consumer<EntryNotification> listener, int flags)
Add a listener for all entries starting with a certain prefix.int
addLogger(Consumer<LogMessage> func, int minLevel, int maxLevel)
Add logger callback function.void
close()
Destroys the instance (if created bycreate()
).static NetworkTableInstance
create()
Create an instance.void
createRpc(NetworkTableEntry entry, Consumer<RpcAnswer> callback)
Create a callback-based RPC entry point.void
deleteAllEntries()
Deletes ALL keys in ALL subtables (except persistent values).boolean
equals(Object other)
void
flush()
Flushes all updated values immediately to the network.ConnectionInfo[]
getConnections()
Gets information on the currently established network connections.static NetworkTableInstance
getDefault()
Get global default instance.NetworkTableEntry[]
getEntries(String prefix, int types)
Get entries starting with the given prefix.NetworkTableEntry
getEntry(String name)
Gets the entry for a key.EntryInfo[]
getEntryInfo(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(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.String[]
loadEntries(String filename, String prefix)
Load table values from a file.String[]
loadPersistent(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(String filename, String prefix)
Save table values to a file.void
savePersistent(String filename)
Saves persistent keys to a file.void
setNetworkIdentity(String name)
Set the network identity of this node.void
setServer(String serverName)
Sets server address and port for client (without restarting client).void
setServer(String[] serverNames)
Sets server addresses and port for client (without restarting client).void
setServer(String[] serverNames, int port)
Sets server addresses and port for client (without restarting client).void
setServer(String[] serverNames, int[] ports)
Sets server addresses and ports for client (without restarting client).void
setServer(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(String serverName)
Starts a client using the specified server and the default port.void
startClient(String[] serverNames)
Starts a client using the specified servers and default port.void
startClient(String[] serverNames, int port)
Starts a client using the specified servers and port number.void
startClient(String[] serverNames, int[] ports)
Starts a client using the specified (server, port) combinations.void
startClient(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
startLocal()
Starts local-only operation.void
startServer()
Starts a server using the networktables.ini as the persistent file, using the default listening address and port.void
startServer(String persistFilename)
Starts a server using the specified persistent filename, using the default listening address and port.void
startServer(String persistFilename, String listenAddress)
Starts a server using the specified filename and listening address, using the default port.void
startServer(String persistFilename, 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
stopLocal()
Stops local-only operation.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.
-
-
-
Field Detail
-
kNetModeNone
public static final int kNetModeNone
Client/server mode flag values (as returned bygetNetworkMode()
). 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
-
kNetModeLocal
public static final int kNetModeLocal
- 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
-
close
public void close()
Destroys the instance (if created bycreate()
).- Specified by:
close
in interfaceAutoCloseable
-
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 returnedtypes
- 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 returnedtypes
- 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 prefixlistener
- listener to addflags
-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 entrylistener
- listener to addflags
-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 addimmediateNotify
- 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 entrycallback
- 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 uselistenAddress
- 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 uselistenAddress
- the address to listen on, or empty to listen on any addressport
- 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 nameport
- 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 namesport
- 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 namesports
- 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 numberport
- 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 nameport
- 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 namesport
- 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 namesports
- 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 numberport
- 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
- filenameprefix
- 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
- filenameprefix
- 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 functionminLevel
- minimum log levelmaxLevel
- 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.
-
-