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


Method Summary
 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.
 boolean loginNoThrow(java.lang.String name, java.lang.String passwd)
          Login to an NML server using a name and passwd.
 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 -

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 -

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 -

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 -

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 -

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 -

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

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

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?

loginNoThrow

boolean loginNoThrow(java.lang.String name,
                     java.lang.String passwd)
Login to an NML server using a name and passwd.

Parameters:
name -
passwd -
Returns:
true if successful, false otherwise

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

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

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 -

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 -

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 -

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 -
Returns:
singleVarLog

closeSingleVarLog

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

Parameters:
var_log_number -
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