rcs.nml

Interface NMLConnectionInterface

All Known Implementing Classes:

NMLConnection

public interface NMLConnectionInterface

An interface to NMLConnection used by CodeGenenerator and diagnostics tool to avoid circular dependencies.

Method Summary

Modifier and Type	Method and Description
int	closeSingleVarLog(int var_log_number) Stop collecting data on a single variable setup in setupSingleVarLog().
int	connect() Connect or reconnect to the sockets as appropriate.
int	connectNoThrow() Connect as connect() but simply print a message to strderr and return -1 in case of an error rather than throwing an exception.
void	disconnect() Disconnect closing all sockets.
java.lang.String	get_buffer_name() Get the buffer name.
int	get_buffer_number() Get the buffer_number for this buffer.
java.lang.String	get_configuration_file() Get the name of the NML configuration file being used.
long	get_connect_time() Get the time in milliseconds when the last connect() was attempted.
long	get_disconnect_time() Get the time in milliseconds when the last disconnect() was attempted.
java.lang.String	get_host() Get the host name where the buffer is supposed to be located.
java.lang.String	get_last_exception_string() Get the message string associated with the last exception thrown including those printed but caught internally by NoThrow functions.
int	get_last_id_read() Each message has an id used to determine if it is new.
int	get_msg_count() Get the number of messages that have been successfully written to the buffer, including messages written by other processes/systems.
int	get_msg_type() Get the type of message in the currently in the buffer.
int	get_port() Return the TCP or UDP port number associated with this connection.
java.lang.String	get_process_name() Get the process name.
java.lang.String	get_returned_buffer_name() When the NMLConnection performs a verify bufname (which it normally does in the constructor) it requests the buffername from the server that corresponds to the selected port and buffer number.
int	getAllocation_size_max()
java.lang.String	getBufferLine() Get the buffer line from the configuration file.
int	getNoThrowErrorCount() Get the number of times a NoThrow fuction returned -1 for this object.
NMLSingleVarLog	getSingleVarLog(int var_log_number) Get a NMLSingleVaLog object associated with the var_log_number that should have been returned by setupSingleVarLog()
boolean	is_connected() Get the value of the connected property.
java.lang.String	peekDataStringNoThrow() Peek a message and convert it to a comma delimeted string.
java.lang.String	read_errlog_string()
java.lang.String	readDataStringNoThrow() Read a message and convert it to a comma delimeted string.
void	ReadNMLConfigurationFileNoThrow() Reread the NML Configuration and reconnect.
void	set_buffer_name(java.lang.String _buffer_name) Set the buffer name.
void	set_buffer_number(int _buffer_number) Set the buffer_number for this buffer.
void	set_configuration_file(java.lang.String _configuration_file) Set the name of the NML configuration file.
void	set_host(java.lang.String s) Set the host name where the buffer is supposed to be located which will be used for the next connection attempt.
void	set_last_id_read(int _id) Set the id which will be compared with messages recieved to determine if the message is new.
void	set_port(int _port) Set the TCP or UDP port to be used for the next time a connect() is performed.
void	set_process_name(java.lang.String _process_name) Set the process name.
void	setAllocation_size_max(int allocation_size_max)
void	SetFormatConvertErrCallback(NMLFormatConvertErrCallbackInterface new_nfceci) Set an interface that will have its member functions called for various errors.
void	SetMessageDictionary(NMLMessageDictionary new_dict) Set the message dictionary.
int	setupSingleVarLog(java.lang.String varname, int maxlogsize, double period, int type) Setup a single variable log.
boolean	verify_bufname() When the NMLConnection performs a verify bufname (which it normally does in the constructor) it requests the buffername from the server that corresponds to the selected port and buffer number.
int	writeDataString(java.lang.String s) Convert the string into an NMLmsg and send it to this channel.
int	writeDataStringNoThrow(java.lang.String s) Convert the string into an NMLmsg and send it to this channel.

Method Detail

get_connect_time

long get_connect_time()

Get the time in milliseconds when the last connect() was attempted. (To determin how long it has been since the last connection subtract from the current time given with System.currentTimeMillis();

Returns:

connect_time

get_disconnect_time

long get_disconnect_time()

Get the time in milliseconds when the last disconnect() was attempted. (To determin how long it has been since disconnected subtract from the current time given with System.currentTimeMillis();

Returns:

disconnect_time

get_returned_buffer_name

java.lang.String get_returned_buffer_name()

When the NMLConnection performs a verify bufname (which it normally does in the constructor) it requests the buffername from the server that corresponds to the selected port and buffer number. If this is not the same as the buffer passed to the constructor it indicates that configuration used by the server is inconsistant with the one being used by this process. Regardless the value is stored and can be retrieved later with get_returned_buffer_name().

Returns:

returned_buffer_name

verify_bufname

boolean verify_bufname()

When the NMLConnection performs a verify bufname (which it normally does in the constructor) it requests the buffername from the server that corresponds to the selected port and buffer number. If this is not the same as the buffer passed to the constructor it indicates that configuration used by the server is inconsistant with the one being used by this process.

Returns:

true if the host could be contacted and returned the expected buffername, or false if the server could not be contacted or the buffernames do not match.

get_host

java.lang.String get_host()

Get the host name where the buffer is supposed to be located. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Returns:

host

set_host

void set_host(java.lang.String s)

Set the host name where the buffer is supposed to be located which will be used for the next connection attempt. Either host names or IP addresses can be used. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Parameters:

s - new hostname

get_port

int get_port()

Return the TCP or UDP port number associated with this connection. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Returns:

port number

set_port

void set_port(int _port)

Set the TCP or UDP port to be used for the next time a connect() is performed. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Parameters:

_port - new port number

get_buffer_number

int get_buffer_number()

Get the buffer_number for this buffer. The buffer number is sent with each request to the server to identify which buffer should be used. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Returns:

buffer_number

set_buffer_number

void set_buffer_number(int _buffer_number)

Set the buffer_number for this buffer. The buffer number is sent with each request to the server to identify which buffer should be used. This is normally obtained from the BufferLine of the config file or from the nmlcfgsvr.

Parameters:

_buffer_number - new buffer number

get_configuration_file

java.lang.String get_configuration_file()

Get the name of the NML configuration file being used.

Returns:

configuration_file

set_configuration_file

void set_configuration_file(java.lang.String _configuration_file)

Set the name of the NML configuration file. This should be followed with ReadNMLConfigurationFileNoThrow() to actually have the configration file read.

Parameters:

_configuration_file - new configuration file

get_buffer_name

java.lang.String get_buffer_name()

Get the buffer name. This is normally set by being passed as an argument to the NMLConnection() constructor.

Returns:

buffer_name

set_buffer_name

void set_buffer_name(java.lang.String _buffer_name)

Set the buffer name. This is normally set by being passed as an argument to the NMLConnection() constructor.

Parameters:

_buffer_name - new buffer name

get_process_name

java.lang.String get_process_name()

Get the process name. This is normally set by being passed as an argument to the NMLConnection() constructor.

Returns:

process_name

set_process_name

void set_process_name(java.lang.String _process_name)

Set the process name. This is normally set by being passed as an argument to the NMLConnection() constructor.

Parameters:

_process_name - new process name

disconnect

void disconnect()

Disconnect closing all sockets.

connectNoThrow

int connectNoThrow()

Connect as connect() but simply print a message to strderr and return -1 in case of an error rather than throwing an exception. NOTE: ReadNMLConfigurationFile and the NMLConnection() constructor with 4 arguments. call connect() internally so it is only necessary to call this if the first connect() failed, or disconnect() was called or the 0 arguments constructor was used to createt the NMLConnection.

Returns:

0 connect was ok. -1 error occured.

connect

int connect()
     throws java.lang.Exception

Connect or reconnect to the sockets as appropriate. Most errors throw an exception. Unfortunately the return value also needs to be checked since a few errors only cause a -1 return value. NOTE: ReadNMLConfigurationFile and the NMLConnection() constructor with 4 arguments. call connect() internally so it is only necessary to call this if the first connect() failed, or disconnect() was called or the 0 arguments constructor was used to createt the NMLConnection. *

Returns:

0 connect was ok. -1 error occured.

Throws:

java.lang.Exception - when connection fails

writeDataString

int writeDataString(java.lang.String s)
             throws NMLException

Convert the string into an NMLmsg and send it to this channel. Depending on the server configuration the string may also be sent directly to the server to be converted on the server end. The string should be comma delimited starting with the type and size. ie: 1001,0,99

Parameters:

s - string to be converted

Returns:

0 write ok, -1 an error occured.

Throws:

NMLException - when write fails

writeDataStringNoThrow

int writeDataStringNoThrow(java.lang.String s)

Convert the string into an NMLmsg and send it to this channel. Depending on the server configuration the string may also be sent directly to the server to be converted on the server end. The string should be comma delimited starting with the type and size. ie: 1001,0,99 The same as writeDataString except it never throws an exception merely prints a message and returns -1.

Parameters:

s - string to be converted

Returns:

0 write ok, -1 an error occured.

readDataStringNoThrow

java.lang.String readDataStringNoThrow()

Read a message and convert it to a comma delimeted string. Depending on the server configuration the string might also be sent from a server that did the conversion on the server side. It marks the buffer as read and removes the message from the queue if the buffer is queued. It is the same as readDataString except it prints a error message and returns -1 instead of throwing an exception.

Returns:

message read in comma delimited form.

peekDataStringNoThrow

java.lang.String peekDataStringNoThrow()

Peek a message and convert it to a comma delimeted string. Depending on the server configuration the string might also be sent from a server that did the conversion on the server side. Peeking is the same as reading except that it does not modify the buffer it reads. It does not mark the buffer as read or remove the message from a queued_buffer. It is the same as peekDataString except it prints a error message and returns -1 instead of throwing an exception.

Returns:

message read in comma delimited form.

is_connected

boolean is_connected()

Get the value of the connected property. Set to true by a successful connect() or constructor set to false by disconnect().

Returns:

Is the Channel and its underlying socket connected?

getBufferLine

java.lang.String getBufferLine()

Get the buffer line from the configuration file.

Returns:

BufferLine

getNoThrowErrorCount

int getNoThrowErrorCount()

Get the number of times a NoThrow fuction returned -1 for this object.

Returns:

noThrowErrorCount.

get_msg_type

int get_msg_type()
          throws java.lang.Exception

Get the type of message in the currently in the buffer. NOTEL: another process may change this before you have a chance to read the message.

Returns:

msg_type

Throws:

java.lang.Exception - when get_msg_type fails

get_msg_count

int get_msg_count()
           throws java.lang.Exception

Get the number of messages that have been successfully written to the buffer, including messages written by other processes/systems.

Returns:

msg_count

Throws:

java.lang.Exception - when get_msg_count fails

get_last_id_read

int get_last_id_read()

Each message has an id used to determine if it is new.

Returns:

id of last message read.

set_last_id_read

void set_last_id_read(int _id)

Set the id which will be compared with messages recieved to determine if the message is new. A message in new if its id does not equal the value set here.

Parameters:

_id - new value for id

ReadNMLConfigurationFileNoThrow

void ReadNMLConfigurationFileNoThrow()

Reread the NML Configuration and reconnect. Same as ReadNMLConfiguration() except errors are only printed to stderr and no exceptions are thrown.

SetMessageDictionary

void SetMessageDictionary(NMLMessageDictionary new_dict)

Set the message dictionary. The message dictionary sets the set of message types that can be read or written from this channel.

Parameters:

new_dict - new dictionary object

SetFormatConvertErrCallback

void SetFormatConvertErrCallback(NMLFormatConvertErrCallbackInterface new_nfceci)

Set an interface that will have its member functions called for various errors. Used by the diagnostics tools to improve error reporting.

Parameters:

new_nfceci - new callback object

setupSingleVarLog

int setupSingleVarLog(java.lang.String varname,
                      int maxlogsize,
                      double period,
                      int type)

Setup a single variable log. Occationally it is useful to read only a single variable from a large message and there for reduce the amount of bandwidth required to log that variable.

Parameters:

varname - name of the variable to log

maxlogsize - maximum number of variable updates to store

period - time in seconds between checks to see if the variable changed.

type - type of expected message, no data is logged when other message types are in the buffer.

Returns:

-1 if an error occurs, positive integer id of the log used with getSingleVarLog(), and closeSingleVarLog()

getSingleVarLog

NMLSingleVarLog getSingleVarLog(int var_log_number)

Get a NMLSingleVaLog object associated with the var_log_number that should have been returned by setupSingleVarLog()

Parameters:

var_log_number - number assoctiated with var_log

Returns:

singleVarLog

closeSingleVarLog

int closeSingleVarLog(int var_log_number)

Stop collecting data on a single variable setup in setupSingleVarLog().

Parameters:

var_log_number - number associated with var log

Returns:

0 ok, -1 comm error in sending close request.

get_last_exception_string

java.lang.String get_last_exception_string()

Get the message string associated with the last exception thrown including those printed but caught internally by NoThrow functions.

Returns:

exception_string

getAllocation_size_max

int getAllocation_size_max()

setAllocation_size_max

void setAllocation_size_max(int allocation_size_max)

read_errlog_string

java.lang.String read_errlog_string()
                             throws NMLException

Throws:

NMLException