rcs.nml
Class NMLConnection

java.lang.Object
  extended by rcs.nml.NMLConnection
All Implemented Interfaces:
NMLConnectionInterface

public class NMLConnection
extends java.lang.Object
implements NMLConnectionInterface

Class for connecting to NML buffers, ussually via network sockets.

 Related Documentation:
 RCS Library, NML Programmers Guide (Java Version)

 


Field Summary
protected  boolean bad_host
           
protected static int CMS_CHECK_IF_READ_ACCESS
           
protected static int CMS_PEEK_ACCESS
           
protected static int CMS_READ_ACCESS
           
protected static int CMS_WRITE_ACCESS
           
protected static int CMS_WRITE_IF_READ_ACCESS
           
static NMLConnectionCreator Creator
          Creator singleton used to avoid circular dependancies in old diagapplet/codegen/rcs design code.
static boolean do_not_print_errors
           
protected  NMLFormatConverterBase format_converter
           
static boolean keep_old_configs
          Should NML store configuration data to make connecting to new buffers faster? Default : true
protected  NMLmsg last_msg_read
           
protected  NMLMessageDictionary message_dictionary
           
protected  NMLFormatConvertErrCallbackInterface nfceci
           
protected static int NML_ASCII_ENCODING_TYPE
           
protected static int NML_DISP_ENCODING_TYPE
           
protected static int NML_PACKED_ENCODING_TYPE
           
protected static int NML_PACKEDL64_ENCODING_TYPE
           
protected static int NML_STCP_PROTOCOL_TYPE
           
protected static int NML_TCP_PROTOCOL_TYPE
           
protected static int NML_UDP_PROTOCOL_TYPE
           
protected static int NML_XDR_ENCODING_TYPE
           
protected static int NML_XML_ENCODING_TYPE
           
protected  int output_data_size
           
protected static java.util.Hashtable previously_read_nml_configurations
           
protected  int protocol_option
           
protected  boolean read_request_sent
           
protected static int REMOTE_CMS_BLOCKING_READ_REQUEST_TYPE
           
protected static int REMOTE_CMS_CANCEL_SUBSCRIPTION_REQUEST_TYPE
           
protected static int REMOTE_CMS_CLOSE_SINGLE_VAR_LOG_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_BUF_NAME_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_DIAG_INFO_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_IS_CLEAR_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_KEYS_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_MSG_COUNT_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_MSG_TYPE_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_QUEUE_LENGTH_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_READ_COUNT_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_SINGLE_VAR_LOG_REQUEST_TYPE
           
protected static int REMOTE_CMS_GET_SPACE_AVAILABLE_REQUEST_TYPE
           
protected static int REMOTE_CMS_LOGIN_REQUEST_TYPE
           
protected static int REMOTE_CMS_READ_COMBINED_REQUEST_TYPE
           
protected static int REMOTE_CMS_READ_REQUEST_TYPE
           
protected static int REMOTE_CMS_SET_DIAG_INFO_REQUEST_TYPE
           
protected static int REMOTE_CMS_SET_SUBSCRIPTION_REQUEST_TYPE
           
protected static int REMOTE_CMS_SETUP_SINGLE_VAR_LOG_REQUEST_TYPE
           
protected static int REMOTE_CMS_WAIT_FOR_ANYTHING_REQUEST_TYPE
           
protected static int REMOTE_CMS_WAIT_FOR_CLEAR_REQUEST_TYPE
           
protected static int REMOTE_CMS_WAIT_FOR_QUEUE_LENGTH_REQUEST_TYPE
           
protected static int REMOTE_CMS_WAIT_FOR_READ_REQUEST_TYPE
           
protected static int REMOTE_CMS_WAIT_FOR_WRITE_REQUEST_TYPE
           
protected static int REMOTE_CMS_WRITE_REQUEST_TYPE
           
protected static int REMOTE_CMS_WRITE_WITH_BITWISE_OP_REQUEST_TYPE
           
protected static int REMOTE_CMS_WRITE_WITH_PRIORITY_REQUEST_TYPE
           
protected  long request_sent_time_millis
           
protected static java.util.Vector unknown_hosts_vector
           
 
Constructor Summary
NMLConnection()
          This constructs an NMLConnection which will not work until the host and port are set manually or by reading the NML configuration file with ReadNMLConfigurationFile().
NMLConnection(NMLMessageDictionary msg_dict, java.lang.String BufferName, java.lang.String ProcessName, java.lang.String ConfigurationFile)
          This constuctor creates a fully functional NML Connection using the application defined NMLMessageDictionary, read the NML configuration file, and connects immediately.
NMLConnection(NMLMessageDictionary msg_dict, java.lang.String BufferName, java.lang.String ProcessName, java.lang.String ConfigurationFile, java.lang.String[] _additional_options)
          This constuctor creates a fully functional NML Connection using the application defined NMLMessageDictionary, read the NML configuration file, and connects immediately.
 
Method Summary
static void AddNMLErrorAppender(NMLErrorAppender nea)
          Add an opject to be called with each error to append messages.
protected  int cancelUDPSubscription()
           
static void ClearStaticData()
          Clear any data saved from previously read configuration files.
 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 this object from the NML server.
protected  void finalize()
           
 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()
          Stop collecting data on a single variable setup in setupSingleVarLog().
 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.
static NMLConfigInfo GetAllConfigInfoFromServer(java.lang.String server)
           
 int getAllocation_size_max()
           
 java.lang.String getBufferLine()
          Get the buffer line from the configuration file.
static NMLConfigInfo GetConfigInfo(java.lang.String configuration_file)
          Parse or return configution info from a previously parsed NML configuration file.
 NMLFormatConverter GetFormatConverter()
          This functions gets the NMLFormatConverter for this connection.
 NMLMessageDictionary GetMessageDictionary()
          This functions gets the NMLMessageDictionary for this connection.
 int getNoThrowErrorCount()
          Get the number of times a NoThrow fuction returned -1 for this object.
 long getRequest_sent_time_millis()
          Get the value of request_sent_time_millis
 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.
static boolean isDefault_poll_state()
           
 boolean isPoll()
           
 boolean isRead_only()
           
 boolean isWrite_only()
           
 boolean login(java.lang.String name, java.lang.String passwd)
          This function allows the application to gain access to NML servers with security enabled.
 boolean loginNoThrow(java.lang.String _name, java.lang.String _passwd)
          Login to an NML server using a name and passwd.
protected  boolean loginTCP(java.lang.String name, java.lang.String passwd)
           
 void ParseAdditionalOptions(java.lang.String[] _additional_options)
           
protected  void peek_raw_data()
           
 NMLmsg peek()
          Read an NMLmsg but do not change the was_read flag.
 java.lang.String peekDataString()
          Reads an NMLmsg using peek() and converts it to a String.
 java.lang.String peekDataStringNoThrow()
          Peek a message and convert it to a comma delimeted string.
protected  java.lang.String peekSTCPDataString()
           
protected  void peekTCP_raw_data()
           
protected  NMLmsg peekTCP()
           
protected  void peekUDP_raw_data()
           
protected  NMLmsg peekUDP()
           
 java.lang.String read_errlog_string()
           
protected  void read_raw_data()
           
 NMLmsg read()
          Read a NMLmsg.
 java.lang.String readDataString()
          Reads an NMLmsg and converts it to a String.
 java.lang.String readDataStringNoThrow()
          Read a message and convert it to a comma delimeted string.
 void ReadNMLConfigurationFile()
          Rereadn the NML Configuration file.
 void ReadNMLConfigurationFile(java.lang.String BufferName, java.lang.String ProcessName, java.lang.String ConfigurationFile)
          This function reads configuration information from the NML configuration file.
 void ReadNMLConfigurationFileNoThrow()
          Reread the NML Configuration and reconnect.
protected  java.lang.String readSTCPDataString()
           
protected  void readTCP_raw_data()
           
protected  NMLmsg readTCP()
           
protected  void readUDP_raw_data()
           
protected  NMLmsg readUDP()
           
 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.
static void set_config_debug_on(boolean b)
          Print messages to the console/stderr to debug the config related code.
 void set_configuration_file(java.lang.String _configuration_file)
          Set the name of the NML configuration file.
 void set_host(java.lang.String _host)
          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 set_read_debug_on(boolean b)
           
 void set_write_debug_on(boolean b)
           
 void setAllocation_size_max(int allocation_size_max)
           
static void setDefault_poll_state(boolean aDefault_poll_state)
           
 int setDiagInfo()
          Send additional diagnostics info to server so it can better track which process is doing what.
 void SetFormatConverter(NMLFormatConverter new_fc)
          This functions sets the NMLFormatConverter for this connection.
 void SetFormatConvertErrCallback(NMLFormatConvertErrCallbackInterface new_nfceci)
          Set an interface that will have its member functions called for various errors.
 void SetMessageDictionary(NMLMessageDictionary new_dict)
          This functions sets the NMLMessageDictionary for this connection.
 void setPoll(boolean poll)
           
 void setRead_only(boolean read_only)
           
 int setSubscriptionPeriod(double period)
          Tell the server to send this process messages from the buffer every period seconds without needing a request message.
protected  int setTCPDiagInfo()
           
protected  int setTCPSubscriptionPeriod(double period)
           
protected  int setUDPSubscriptionPeriod(double period)
           
 int setupSingleVarLog(java.lang.String varname, int maxlogsize, double period, int type)
          Setup a single variable log.
 void setWrite_only(boolean write_only)
           
 java.lang.String toString()
           
protected  int UDP_get_msg_count()
           
protected  int UDP_get_msg_type()
           
 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.
protected  boolean verify_bufnameTCP()
           
 int write(NMLmsg msg)
          Writes an NMLmsg.
 int writeDataString(java.lang.String dataString)
          Convert the string into an NMLmsg and send it to this channel.
 int writeDataStringNoThrow(java.lang.String dataString)
          Convert the string into an NMLmsg and send it to this channel.
protected  int writeSTCPDataString(java.lang.String dataString)
           
protected  int writeTCP(NMLmsg msg)
           
protected  int writeUDP(NMLmsg msg)
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

previously_read_nml_configurations

protected static java.util.Hashtable previously_read_nml_configurations

format_converter

protected NMLFormatConverterBase format_converter

message_dictionary

protected NMLMessageDictionary message_dictionary

NML_STCP_PROTOCOL_TYPE

protected static final int NML_STCP_PROTOCOL_TYPE
See Also:
Constant Field Values

NML_TCP_PROTOCOL_TYPE

protected static final int NML_TCP_PROTOCOL_TYPE
See Also:
Constant Field Values

NML_UDP_PROTOCOL_TYPE

protected static final int NML_UDP_PROTOCOL_TYPE
See Also:
Constant Field Values

protocol_option

protected int protocol_option

NML_ASCII_ENCODING_TYPE

protected static final int NML_ASCII_ENCODING_TYPE
See Also:
Constant Field Values

NML_DISP_ENCODING_TYPE

protected static final int NML_DISP_ENCODING_TYPE
See Also:
Constant Field Values

NML_XDR_ENCODING_TYPE

protected static final int NML_XDR_ENCODING_TYPE
See Also:
Constant Field Values

NML_XML_ENCODING_TYPE

protected static final int NML_XML_ENCODING_TYPE
See Also:
Constant Field Values

NML_PACKED_ENCODING_TYPE

protected static final int NML_PACKED_ENCODING_TYPE
See Also:
Constant Field Values

NML_PACKEDL64_ENCODING_TYPE

protected static final int NML_PACKEDL64_ENCODING_TYPE
See Also:
Constant Field Values

REMOTE_CMS_READ_REQUEST_TYPE

protected static final int REMOTE_CMS_READ_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WRITE_REQUEST_TYPE

protected static final int REMOTE_CMS_WRITE_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_KEYS_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_KEYS_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_LOGIN_REQUEST_TYPE

protected static final int REMOTE_CMS_LOGIN_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_SET_SUBSCRIPTION_REQUEST_TYPE

protected static final int REMOTE_CMS_SET_SUBSCRIPTION_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_READ_COMBINED_REQUEST_TYPE

protected static final int REMOTE_CMS_READ_COMBINED_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_BLOCKING_READ_REQUEST_TYPE

protected static final int REMOTE_CMS_BLOCKING_READ_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_BUF_NAME_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_BUF_NAME_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_CANCEL_SUBSCRIPTION_REQUEST_TYPE

protected static final int REMOTE_CMS_CANCEL_SUBSCRIPTION_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_SET_DIAG_INFO_REQUEST_TYPE

protected static final int REMOTE_CMS_SET_DIAG_INFO_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_DIAG_INFO_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_DIAG_INFO_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_MSG_COUNT_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_MSG_COUNT_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_QUEUE_LENGTH_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_QUEUE_LENGTH_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_SPACE_AVAILABLE_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_SPACE_AVAILABLE_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WRITE_WITH_PRIORITY_REQUEST_TYPE

protected static final int REMOTE_CMS_WRITE_WITH_PRIORITY_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WRITE_WITH_BITWISE_OP_REQUEST_TYPE

protected static final int REMOTE_CMS_WRITE_WITH_BITWISE_OP_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WAIT_FOR_WRITE_REQUEST_TYPE

protected static final int REMOTE_CMS_WAIT_FOR_WRITE_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WAIT_FOR_READ_REQUEST_TYPE

protected static final int REMOTE_CMS_WAIT_FOR_READ_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WAIT_FOR_QUEUE_LENGTH_REQUEST_TYPE

protected static final int REMOTE_CMS_WAIT_FOR_QUEUE_LENGTH_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WAIT_FOR_CLEAR_REQUEST_TYPE

protected static final int REMOTE_CMS_WAIT_FOR_CLEAR_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_WAIT_FOR_ANYTHING_REQUEST_TYPE

protected static final int REMOTE_CMS_WAIT_FOR_ANYTHING_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_READ_COUNT_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_READ_COUNT_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_IS_CLEAR_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_IS_CLEAR_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_SETUP_SINGLE_VAR_LOG_REQUEST_TYPE

protected static final int REMOTE_CMS_SETUP_SINGLE_VAR_LOG_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_SINGLE_VAR_LOG_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_SINGLE_VAR_LOG_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_CLOSE_SINGLE_VAR_LOG_REQUEST_TYPE

protected static final int REMOTE_CMS_CLOSE_SINGLE_VAR_LOG_REQUEST_TYPE
See Also:
Constant Field Values

REMOTE_CMS_GET_MSG_TYPE_REQUEST_TYPE

protected static final int REMOTE_CMS_GET_MSG_TYPE_REQUEST_TYPE
See Also:
Constant Field Values

bad_host

protected boolean bad_host

unknown_hosts_vector

protected static java.util.Vector unknown_hosts_vector

CMS_READ_ACCESS

protected static final int CMS_READ_ACCESS
See Also:
Constant Field Values

CMS_CHECK_IF_READ_ACCESS

protected static final int CMS_CHECK_IF_READ_ACCESS
See Also:
Constant Field Values

CMS_PEEK_ACCESS

protected static final int CMS_PEEK_ACCESS
See Also:
Constant Field Values

CMS_WRITE_ACCESS

protected static final int CMS_WRITE_ACCESS
See Also:
Constant Field Values

CMS_WRITE_IF_READ_ACCESS

protected static final int CMS_WRITE_IF_READ_ACCESS
See Also:
Constant Field Values

output_data_size

protected int output_data_size

last_msg_read

protected NMLmsg last_msg_read

read_request_sent

protected boolean read_request_sent

do_not_print_errors

public static boolean do_not_print_errors

nfceci

protected NMLFormatConvertErrCallbackInterface nfceci

keep_old_configs

public static boolean keep_old_configs
Should NML store configuration data to make connecting to new buffers faster? Default : true


request_sent_time_millis

protected long request_sent_time_millis

Creator

public static final NMLConnectionCreator Creator
Creator singleton used to avoid circular dependancies in old diagapplet/codegen/rcs design code.

Constructor Detail

NMLConnection

public NMLConnection()
This constructs an NMLConnection which will not work until the host and port are set manually or by reading the NML configuration file with ReadNMLConfigurationFile(). Most users should use the other constructor with several parameters.

See Also:
NMLConnection(rcs.nml.NMLMessageDictionary, java.lang.String, java.lang.String, java.lang.String), ReadNMLConfigurationFile(java.lang.String, java.lang.String, java.lang.String)

NMLConnection

public NMLConnection(NMLMessageDictionary msg_dict,
                     java.lang.String BufferName,
                     java.lang.String ProcessName,
                     java.lang.String ConfigurationFile)
              throws NMLException
This constuctor creates a fully functional NML Connection using the application defined NMLMessageDictionary, read the NML configuration file, and connects immediately. This is the constructor most users should use.

Parameters:
msg_dict - the NMLMessageDictionary for this connection to use (the NMLMessageDictionary allows this Connection to determine the message structure from the message type)
BufferName - the name of the buffer to connect to, (must match one of the buffers in the configuration file.)
ProcessName - the name of the process that will use this connection (must match one of the process names in the configuration file)
ConfigurationFile - the file name or URL of an NML configuration file (URL's should either be complete, or they can be relative to rcs.utils.URL_and_FileLoader.current_directory)
Throws:
NMLException - If the configuration file can not be read, the file is improperly formatted or the buffer or process can can not be found in it.

NMLConnection

public NMLConnection(NMLMessageDictionary msg_dict,
                     java.lang.String BufferName,
                     java.lang.String ProcessName,
                     java.lang.String ConfigurationFile,
                     java.lang.String[] _additional_options)
              throws NMLException
This constuctor creates a fully functional NML Connection using the application defined NMLMessageDictionary, read the NML configuration file, and connects immediately. This is the constructor most users should use.

Parameters:
msg_dict - the NMLMessageDictionary for this connection to use (the NMLMessageDictionary allows this Connection to determine the message structure from the message type)
BufferName - the name of the buffer to connect to, (must match one of the buffers in the configuration file.)
ProcessName - the name of the process that will use this connection (must match one of the process names in the configuration file)
ConfigurationFile - the file name or URL of an NML configuration file (URL's should either be complete, or they can be relative to rcs.utils.URL_and_FileLoader.current_directory)
_additional_options -
Throws:
NMLException - If the configuration file can not be read, the file is improperly formatted or the buffer or process can can not be found in it.
Method Detail

isDefault_poll_state

public static boolean isDefault_poll_state()
Returns:
the default_poll_state

setDefault_poll_state

public static void setDefault_poll_state(boolean aDefault_poll_state)
Parameters:
aDefault_poll_state - the default_poll_state to set

get_connect_time

public 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();

Specified by:
get_connect_time in interface NMLConnectionInterface
Returns:
connect_time

get_disconnect_time

public 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();

Specified by:
get_disconnect_time in interface NMLConnectionInterface
Returns:
disconnect_time

get_last_exception_string

public java.lang.String get_last_exception_string()
Stop collecting data on a single variable setup in setupSingleVarLog().

Specified by:
get_last_exception_string in interface NMLConnectionInterface
Returns:
0 ok, -1 comm error in sending close request.

get_last_id_read

public int get_last_id_read()
Each message has an id used to determine if it is new.

Specified by:
get_last_id_read in interface NMLConnectionInterface
Returns:
id of last message read.

set_last_id_read

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

Specified by:
set_last_id_read in interface NMLConnectionInterface
Parameters:
_id -

get_returned_buffer_name

public 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().

Specified by:
get_returned_buffer_name in interface NMLConnectionInterface
Returns:
returned_buffer_name

getNoThrowErrorCount

public int getNoThrowErrorCount()
Get the number of times a NoThrow fuction returned -1 for this object.

Specified by:
getNoThrowErrorCount in interface NMLConnectionInterface
Returns:
noThrowErrorCount.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

AddNMLErrorAppender

public static void AddNMLErrorAppender(NMLErrorAppender nea)
Add an opject to be called with each error to append messages. Multiple appenders can be added.

Parameters:
nea -

SetMessageDictionary

public void SetMessageDictionary(NMLMessageDictionary new_dict)
This functions sets the NMLMessageDictionary for this connection. The purpose of the NMLMessageDictionary is to provide a means for the NMLConnection to determine the structure of messages being sent or received using a message type. (An integer passed within all NML messages.)

Specified by:
SetMessageDictionary in interface NMLConnectionInterface
Parameters:
new_dict - the NMLMessageDictionary for this NMLConnection to use.
See Also:
NMLMessageDictionary

SetFormatConvertErrCallback

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

Specified by:
SetFormatConvertErrCallback in interface NMLConnectionInterface
Parameters:
new_nfceci -

GetMessageDictionary

public NMLMessageDictionary GetMessageDictionary()
                                          throws NMLException
This functions gets the NMLMessageDictionary for this connection.

Returns:
the implementation of NMLMessageDictionary used by this NMLConnection
Throws:
NMLException
See Also:
SetMessageDictionary(rcs.nml.NMLMessageDictionary), NMLMessageDictionary

SetFormatConverter

public void SetFormatConverter(NMLFormatConverter new_fc)
                        throws NMLException
This functions sets the NMLFormatConverter for this connection. The NMLFormatConverter is resposible for converting each of the basic data types to some neutral format that can be used on many different platforms. Most users should either accept the default (XDRFormatConverter) or allow the format to be specified in the NML configuration file rather than calling this function directly.

Parameters:
new_fc - the NMLFormatConverter for this Connection to use.
Throws:
NMLException
See Also:
NMLFormatConverter

GetFormatConverter

public NMLFormatConverter GetFormatConverter()
                                      throws NMLException
This functions gets the NMLFormatConverter for this connection.

Returns:
the NMLFormatConverter for this connection
Throws:
NMLException
See Also:
SetFormatConverter(rcs.nml.NMLFormatConverter)

ParseAdditionalOptions

public void ParseAdditionalOptions(java.lang.String[] _additional_options)
                            throws NMLException
Throws:
NMLException

ReadNMLConfigurationFile

public void ReadNMLConfigurationFile(java.lang.String BufferName,
                                     java.lang.String ProcessName,
                                     java.lang.String ConfigurationFile)
                              throws NMLException
This function reads configuration information from the NML configuration file.

Parameters:
BufferName - the name of the buffer to connect to, (must match one of the buffers in the configuration file.)
ProcessName - the name of the process that will use this connection (must match one of the process names in the configuration file)
ConfigurationFile - the file name or URL of an NML configuration file (URL's should either be complete, or they can be relative to rcs.utils.URL_and_FileLoader.current_directory)
Throws:
NMLException - If the configuration file can not be read, the file is improperly formatted or the buffer or process can can not be found in it.

ClearStaticData

public static void ClearStaticData()
Clear any data saved from previously read configuration files.


GetConfigInfo

public static NMLConfigInfo GetConfigInfo(java.lang.String configuration_file)
Parse or return configution info from a previously parsed NML configuration file.

Parameters:
configuration_file -
Returns:
nml configuraton info

GetAllConfigInfoFromServer

public static NMLConfigInfo GetAllConfigInfoFromServer(java.lang.String server)

ReadNMLConfigurationFile

public void ReadNMLConfigurationFile()
                              throws NMLException
Rereadn the NML Configuration file.

Throws:
NMLException

finalize

protected void finalize()
Overrides:
finalize in class java.lang.Object

connect

public int connect()
            throws NMLException
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. *

Specified by:
connect in interface NMLConnectionInterface
Returns:
0 connect was ok. -1 error occured.
Throws:
NMLException

disconnect

public void disconnect()
Disconnect this object from the NML server. This allows the NML server to shutdown and come back up while preserving the configuration information in this object. All reads and writes will fail while the object is disconnected.

Specified by:
disconnect in interface NMLConnectionInterface

login

public boolean login(java.lang.String name,
                     java.lang.String passwd)
              throws NMLException
This function allows the application to gain access to NML servers with security enabled.

Parameters:
name - the login name of the user running the client program
passwd - the passwd of the user to login as.
Returns:
true if login was successful
Throws:
NMLException - If the login could not be attempted because the connection to the NML server failed. (If the passwd is wrong it returns false.)

verify_bufname

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

Specified by:
verify_bufname in interface NMLConnectionInterface
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.

read

public NMLmsg read()
            throws NMLException
Read a NMLmsg.

Returns:
null if the message in the buffer has already been read by this NMLConnection, otherwise it returns the NMLmsg read.
Throws:
NMLException - The read failed (ussually because of some network error).

setDiagInfo

public int setDiagInfo()
Send additional diagnostics info to server so it can better track which process is doing what.

Returns:
0 for success, -1 for error

setTCPDiagInfo

protected int setTCPDiagInfo()

setupSingleVarLog

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

Specified by:
setupSingleVarLog in interface NMLConnectionInterface
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 otherwise

getSingleVarLog

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

Specified by:
getSingleVarLog in interface NMLConnectionInterface
Parameters:
var_log_number -
Returns:
singleVarLog

closeSingleVarLog

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

Specified by:
closeSingleVarLog in interface NMLConnectionInterface
Parameters:
var_log_number -
Returns:
0 ok, -1 comm error in sending close request.

setSubscriptionPeriod

public int setSubscriptionPeriod(double period)
Tell the server to send this process messages from the buffer every period seconds without needing a request message.

Parameters:
period -
Returns:
0 for success, -1 for error

setUDPSubscriptionPeriod

protected int setUDPSubscriptionPeriod(double period)

cancelUDPSubscription

protected int cancelUDPSubscription()

setTCPSubscriptionPeriod

protected int setTCPSubscriptionPeriod(double period)

read_raw_data

protected void read_raw_data()
                      throws NMLException
Throws:
NMLException

verify_bufnameTCP

protected boolean verify_bufnameTCP()
                             throws NMLException
Throws:
NMLException

readTCP_raw_data

protected void readTCP_raw_data()
                         throws NMLException
Throws:
NMLException

readTCP

protected NMLmsg readTCP()
                  throws NMLException
Throws:
NMLException

readUDP

protected NMLmsg readUDP()
                  throws NMLException
Throws:
NMLException

readUDP_raw_data

protected void readUDP_raw_data()
                         throws NMLException
Throws:
NMLException

peek

public NMLmsg peek()
            throws NMLException
Read an NMLmsg but do not change the was_read flag.

Returns:
null if the message in the buffer has already been read by this NMLConnection or no message has yet been written to the buffer, otherwise it returns the NMLmsg read.
Throws:
NMLException - The peek failed.

peek_raw_data

protected void peek_raw_data()
                      throws NMLException
Throws:
NMLException

getRequest_sent_time_millis

public long getRequest_sent_time_millis()
Get the value of request_sent_time_millis

Returns:
the value of request_sent_time_millis

peekTCP_raw_data

protected void peekTCP_raw_data()
                         throws NMLException
Throws:
NMLException

peekTCP

protected NMLmsg peekTCP()
                  throws NMLException
Throws:
NMLException

peekUDP

protected NMLmsg peekUDP()
                  throws NMLException
Throws:
NMLException

peekUDP_raw_data

protected void peekUDP_raw_data()
                         throws NMLException
Throws:
NMLException

UDP_get_msg_count

protected int UDP_get_msg_count()
                         throws NMLException
Throws:
NMLException

UDP_get_msg_type

protected int UDP_get_msg_type()
                        throws NMLException
Throws:
NMLException

readDataString

public java.lang.String readDataString()
                                throws NMLException
Reads an NMLmsg and converts it to a String.

Returns:
null if the message in the buffer has already been read by this NMLConnection or no message has yet been written to the buffer, otherwise it returns the NMLmsg read converted to a string. The string is a comma separated list of the parameters in the NMLmsg in the order they are updated, starting with the type and size.
Throws:
NMLException - The read failed.
See Also:
read()

readSTCPDataString

protected java.lang.String readSTCPDataString()
                                       throws NMLException
Throws:
NMLException

peekDataString

public java.lang.String peekDataString()
                                throws NMLException
Reads an NMLmsg using peek() and converts it to a String.

Returns:
null if the message in the buffer has already been read by this NMLConnection or no message has yet been written to the buffer, otherwise it returns the NMLmsg read converted to a string. The string is a comma separated list of the parameters in the NMLmsg in the order they are updated, starting with the type and size.
Throws:
NMLException - The peek failed.
See Also:
peek()

peekSTCPDataString

protected java.lang.String peekSTCPDataString()
                                       throws NMLException
Throws:
NMLException

loginTCP

protected boolean loginTCP(java.lang.String name,
                           java.lang.String passwd)
                    throws NMLException
Throws:
NMLException

writeTCP

protected int writeTCP(NMLmsg msg)

writeUDP

protected int writeUDP(NMLmsg msg)

write

public int write(NMLmsg msg)
          throws NMLException
Writes an NMLmsg.

Parameters:
msg - the NMLmsg to write.
Returns:
0 if the write was successful, -1 if there was an error
Throws:
NMLException

writeDataString

public int writeDataString(java.lang.String dataString)
                    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

Specified by:
writeDataString in interface NMLConnectionInterface
Parameters:
dataString - string to be converted
Returns:
0 write ok, -1 an error occured.
Throws:
NMLException

writeDataStringNoThrow

public int writeDataStringNoThrow(java.lang.String dataString)
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.

Specified by:
writeDataStringNoThrow in interface NMLConnectionInterface
Parameters:
dataString - string to be converted
Returns:
0 write ok, -1 an error occured.

writeSTCPDataString

protected int writeSTCPDataString(java.lang.String dataString)

get_host

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

Specified by:
get_host in interface NMLConnectionInterface
Returns:
host

set_host

public void set_host(java.lang.String _host)
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.

Specified by:
set_host in interface NMLConnectionInterface
Parameters:
_host -

get_configuration_file

public java.lang.String get_configuration_file()
Get the name of the NML configuration file being used.

Specified by:
get_configuration_file in interface NMLConnectionInterface
Returns:
configuration_file

set_configuration_file

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

Specified by:
set_configuration_file in interface NMLConnectionInterface
Parameters:
_configuration_file -

get_buffer_name

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

Specified by:
get_buffer_name in interface NMLConnectionInterface
Returns:
buffer_name

set_buffer_name

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

Specified by:
set_buffer_name in interface NMLConnectionInterface
Parameters:
_buffer_name -

get_process_name

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

Specified by:
get_process_name in interface NMLConnectionInterface
Returns:
process_name

set_process_name

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

Specified by:
set_process_name in interface NMLConnectionInterface
Parameters:
_process_name -

readDataStringNoThrow

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

Specified by:
readDataStringNoThrow in interface NMLConnectionInterface
Returns:
message read in comma delimited form.

peekDataStringNoThrow

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

Specified by:
peekDataStringNoThrow in interface NMLConnectionInterface
Returns:
message read in comma delimited form.

get_port

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

Specified by:
get_port in interface NMLConnectionInterface
Returns:
port number

set_port

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

Specified by:
set_port in interface NMLConnectionInterface
Parameters:
_port -

get_buffer_number

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

Specified by:
get_buffer_number in interface NMLConnectionInterface
Returns:
buffer_number

set_buffer_number

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

Specified by:
set_buffer_number in interface NMLConnectionInterface
Parameters:
_buffer_number -

ReadNMLConfigurationFileNoThrow

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

Specified by:
ReadNMLConfigurationFileNoThrow in interface NMLConnectionInterface

connectNoThrow

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

Specified by:
connectNoThrow in interface NMLConnectionInterface
Returns:
0 connect was ok. -1 error occured.

is_connected

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

Specified by:
is_connected in interface NMLConnectionInterface
Returns:
Is the Channel and its underlying socket connected?

loginNoThrow

public boolean loginNoThrow(java.lang.String _name,
                            java.lang.String _passwd)
Login to an NML server using a name and passwd. Same as login except that it never throws exceptions

Specified by:
loginNoThrow in interface NMLConnectionInterface
Parameters:
_name -
_passwd -
Returns:
true if successful, false otherwise

getBufferLine

public java.lang.String getBufferLine()
Get the buffer line from the configuration file.

Specified by:
getBufferLine in interface NMLConnectionInterface
Returns:
BufferLine

set_read_debug_on

public void set_read_debug_on(boolean b)

set_write_debug_on

public void set_write_debug_on(boolean b)

set_config_debug_on

public static void set_config_debug_on(boolean b)
Print messages to the console/stderr to debug the config related code.

Parameters:
b -

read_errlog_string

public java.lang.String read_errlog_string()
                                    throws NMLException
Specified by:
read_errlog_string in interface NMLConnectionInterface
Throws:
NMLException

get_msg_type

public int get_msg_type()
                 throws NMLException
Description copied from interface: NMLConnectionInterface
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.

Specified by:
get_msg_type in interface NMLConnectionInterface
Returns:
msg_type
Throws:
NMLException

get_msg_count

public int get_msg_count()
                  throws NMLException
Description copied from interface: NMLConnectionInterface
Get the number of messages that have been successfully written to the buffer, including messages written by other processes/systems.

Specified by:
get_msg_count in interface NMLConnectionInterface
Returns:
msg_count
Throws:
NMLException

isRead_only

public boolean isRead_only()

setRead_only

public void setRead_only(boolean read_only)

isWrite_only

public boolean isWrite_only()

setWrite_only

public void setWrite_only(boolean write_only)

getAllocation_size_max

public int getAllocation_size_max()
Specified by:
getAllocation_size_max in interface NMLConnectionInterface

setAllocation_size_max

public void setAllocation_size_max(int allocation_size_max)
Specified by:
setAllocation_size_max in interface NMLConnectionInterface

isPoll

public boolean isPoll()
Returns:
the poll

setPoll

public void setPoll(boolean poll)
Parameters:
poll - the poll to set