com.isti.quakewatch.util
Class QWAbstractConnector

java.lang.Object
  extended by com.isti.quakewatch.util.QWAbstractConnector
Direct Known Subclasses:
QWCorbaConnector, QWWebSvcsConnector

public abstract class QWAbstractConnector
extends java.lang.Object

Class QWAbstractConnector defines the interface for the connector modules used by the 'QWConnectionMgr', and some common functionality.


Nested Class Summary
protected static class QWAbstractConnector.ServerHostInfo
          Class ServerHostInfo holds host address string and port number values and provides thread-safe methods for setting and fetching the values.
static class QWAbstractConnector.StatusCheckFailedException
          Class StatusCheckFailedException is thrown by the 'performClientStatusCheck()' method when the call to 'clientStatusCheck()' fails with an exception other than 'NoSuchMethodException'.
 
Field Summary
protected  java.lang.String acceptorRejectIDString
           
protected  java.lang.String acceptorRejectReasonStr
           
protected  byte[] certificateFileDataArr
           
protected  boolean connAttemptFailedFlag
           
protected  boolean connAttemptRejectedFlag
           
protected  boolean connAttemptStartedFlag
           
protected  boolean connectDoneFlag
           
protected  java.lang.String connectionInfoPropsString
           
protected  java.lang.String connectionPasswordString
           
protected  java.lang.String connectionUserNameString
           
protected  boolean connInvalidatedFlag
           
protected  ConnStatusInterface connStatusObj
           
protected  boolean disconnectClientServicesFlag
           
protected  boolean disconnectDoneFlag
           
protected  EncryptDecryptUtil encryptDecryptUtilObj
           
protected  java.lang.String filterDomainTypeListStr
           
protected  EvtChEventType[] filterEventTypeArr
           
protected  LogFile logObj
           
protected  java.lang.String prevStatusMsgTypeNameStr
           
protected static int REQMSGS_NUM_RETRIES
           
protected  QWAbstractConnector.ServerHostInfo serverHostInfoObj
           
protected  java.lang.String serverIdNameString
           
protected  java.lang.String serverRepHostAddrString
           
protected  java.lang.String serverRevisionString
           
protected  java.lang.String statusMsgTypeNameStr
           
protected  boolean statusReportDataAvailFlag
           
 
Constructor Summary
QWAbstractConnector(ConnStatusInterface connStatusObj, LogFile logObj)
          Creates an abstract connector object.
 
Method Summary
 void autoClearConnStatusPopupDialog()
          Clears any displayed connection status popup dialog if the user has not requested that it be shown.
 void clearConnAttemptFailedFlag()
          Clears the connection-attempt-failed flag.
 void clearConnAttemptRejectedFlag()
          Clears the connection-attempt-rejected flag.
 void clearConnAttemptStartedFlag()
          Clears the connection-attempt-started flag.
 void disconnectClientServices()
          Disconnects this client from the server services.
 void disconnectClientServices(boolean sepThreadFlag)
          Disconnects this client from the server services.
protected abstract  boolean doDisconnectClientServices()
          Performs the work of disconnecting this client from the server services.
 void enterConnectionInfo(java.lang.String userNameStr, java.lang.String passwordStr, java.lang.String connPropsStr)
          Enters the connection-information values to be sent when the client connects to the server.
abstract  java.lang.String fetchClientUpgradeInfoFromServer()
          Returns information about available client-program upgrades via the QWServices 'getClientUpgradeInfo()' method.
abstract  java.lang.String fetchRedirectedServerLoc()
          Returns the location of the server that the client is being redirected to.
 byte[] getCertificateFileDataArr()
          Returns the certificate-file data that was fetched from the server at connect time.
 boolean getConnAttemptFailedFlag()
          Returns the connection-attempt-failed flag.
 boolean getConnAttemptRejectedFlag()
          Returns the connection-attempt-rejected flag.
 boolean getConnAttemptStartedFlag()
          Returns the connection-attempt-started flag.
abstract  boolean getConnectedFlag()
          Returns the connection status.
 ConnStatusInterface getConnPanelObj()
          Returns the connection status interface object.
 java.lang.String getDecodedStatusReport()
          Fetches and decodes the latest status report from the server.
 java.lang.String getDetailedServerIDString()
          Returns a more-detailed identification string for the configured server.
abstract  boolean getInitializedFlag()
          Returns the "initialized" status of the connection.
abstract  java.lang.String getServerIDNameStr()
          Returns the server ID name string (defined in the QWServer's configuration file).
 java.lang.String getServerIDString()
          Returns an identification string for the connected server.
abstract  java.lang.String getServerRepHostAddrStr()
          Returns the host address reported by the server.
abstract  java.lang.String getServerRevisionStr()
          Returns the server revision string.
abstract  java.lang.String getStatusReportData()
          Fetches the latest status-report data from the server.
abstract  long getStatusReportTime()
          Fetches the timestamp value for the latest status report from the server.
abstract  void invalidateConnection()
          Marks the connection as "invalidated", causing the 'getConnectedFlag()' method to return 'false'.
abstract  boolean isReqServerMsgsAvailable()
          Returns an indicator of whether or not the 'requestMessages()' method is available via the 'QWServices' on the current server.
abstract  boolean isStatusReportDataAvail()
          Determines if get-status-report methods are available on the server.
abstract  boolean performClientStatusCheck()
          Calls the QWServices 'clientStatusCheck()' method.
abstract  void requestServerAliveMsg()
          Requests that the server send an 'Alive' message immediately.
abstract  java.lang.String requestServerMessages(long timeVal, long msgNum, java.lang.String hostMsgNumListStr)
          Requests that messages newer or equal to the specified time value or later than the specified message number be returned from the server.
 void setAcceptorRejectIDStr(java.lang.String accIDStr, java.lang.String reasonStr)
          Sets the identifier for a QWServer 'Acceptor' that should be rejected when a connection attempt is made.
 void setConnPanelData(java.lang.String textStr, java.lang.String popupStr)
          Sets the message strings for the connection status panel and popup.
 void setConnPanelData(java.lang.String textStr, java.lang.String popupStr, int symColorIdx)
          Sets the message strings for the connection status panel and popup, as well as the color for the symbol on the panel.
protected  void setConnPanelInitError(java.lang.String popupTextStr)
          Sets connection status panel to show an initialization error.
protected  void setConnPanelInitError(java.lang.String popupTextStr, int logLevelVal)
          Sets connection status panel to show an initialization error.
 void setConnStatusRefocusComponent(java.lang.Object compObj)
          Sets the component that is to receive focus after the connection status popup dialog is cleared.
 void setFilterDomainTypeList(java.lang.String listStr)
          Configures this connector's event-message consumer to filter-out (reject) all messages except those with event domain and type names matching the ones specified in the given list string.
 void showConnPanelPopup()
          Shows the popup dialog displaying extra status information for the connection status panel.
abstract  void shutdownConnection(boolean showPopupFlag)
          Shuts down the connection and waits for the disconnect to complete or timeout.
 void startConnectViaHostInfo(java.lang.String serverHostAddrStr, int serverHostPortNum)
          Starts a new thread that connects to the event channel via a connection to a QWServer.
abstract  void startConnectViaHostInfo(java.lang.String serverHostAddrStr, int serverHostPortNum, boolean showPopupFlag)
          Starts a new thread that establishes a connection to a QWServer.
abstract  void updateConnectParams(java.lang.String clientHostAddress, int clientPortNum)
          Updates the connection parameters to be used on the next initialization.
protected  void updateFilterDomainTypeList()
          Builds the contents of the array of event-type objects for message filtering.
 void userRequestShowConnStatusPopupDialog()
          Displays the popup dialog showing extra connection status information in response to a user request.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REQMSGS_NUM_RETRIES

protected static final int REQMSGS_NUM_RETRIES
See Also:
Constant Field Values

connStatusObj

protected final ConnStatusInterface connStatusObj

logObj

protected final LogFile logObj

filterDomainTypeListStr

protected java.lang.String filterDomainTypeListStr

filterEventTypeArr

protected EvtChEventType[] filterEventTypeArr

connectDoneFlag

protected boolean connectDoneFlag

disconnectDoneFlag

protected boolean disconnectDoneFlag

connInvalidatedFlag

protected boolean connInvalidatedFlag

connAttemptStartedFlag

protected boolean connAttemptStartedFlag

connAttemptFailedFlag

protected boolean connAttemptFailedFlag

connAttemptRejectedFlag

protected boolean connAttemptRejectedFlag

disconnectClientServicesFlag

protected boolean disconnectClientServicesFlag

connectionUserNameString

protected java.lang.String connectionUserNameString

connectionPasswordString

protected java.lang.String connectionPasswordString

connectionInfoPropsString

protected java.lang.String connectionInfoPropsString

serverIdNameString

protected java.lang.String serverIdNameString

serverRepHostAddrString

protected java.lang.String serverRepHostAddrString

serverRevisionString

protected java.lang.String serverRevisionString

serverHostInfoObj

protected final QWAbstractConnector.ServerHostInfo serverHostInfoObj

acceptorRejectIDString

protected java.lang.String acceptorRejectIDString

acceptorRejectReasonStr

protected java.lang.String acceptorRejectReasonStr

statusMsgTypeNameStr

protected java.lang.String statusMsgTypeNameStr

prevStatusMsgTypeNameStr

protected java.lang.String prevStatusMsgTypeNameStr

certificateFileDataArr

protected byte[] certificateFileDataArr

statusReportDataAvailFlag

protected boolean statusReportDataAvailFlag

encryptDecryptUtilObj

protected EncryptDecryptUtil encryptDecryptUtilObj
Constructor Detail

QWAbstractConnector

public QWAbstractConnector(ConnStatusInterface connStatusObj,
                           LogFile logObj)
Creates an abstract connector object.

Parameters:
connStatusObj - connection-status panel object, or null for none.
logObj - log-file object to be used, or null for none.
Method Detail

setFilterDomainTypeList

public void setFilterDomainTypeList(java.lang.String listStr)
Configures this connector's event-message consumer to filter-out (reject) all messages except those with event domain and type names matching the ones specified in the given list string. The list string is also used when resend-requesting messages from the server to filter which messages are returned. The list string must be in the format "domain:type,domain:type...". Occurrences of the ':' and ',' characters not meant as separators may be "quoted" by preceding them with the backslash ('\') character. List items missing the ':' character will be considered to specify only a domain name (the type name will be an empty string). If this method is not called then all incoming message will be accepted. If the list string contains data then an entry for the event domain and type name values for status messages ("StatusMessage:serverID/Addr") is appended to the list.

Parameters:
listStr - the list string to use.

updateFilterDomainTypeList

protected void updateFilterDomainTypeList()
Builds the contents of the array of event-type objects for message filtering. This method is called when the list is initially setup and again after the 'statusMsgTypeNameStr' value is retrieved from the server.


updateConnectParams

public abstract void updateConnectParams(java.lang.String clientHostAddress,
                                         int clientPortNum)
Updates the connection parameters to be used on the next initialization.

Parameters:
clientHostAddress - an IP address to be associated with this client, or null to have the address auto-determined.
clientPortNum - a port address value to be associated with this client, or 0 to have the port address auto-determined.

enterConnectionInfo

public void enterConnectionInfo(java.lang.String userNameStr,
                                java.lang.String passwordStr,
                                java.lang.String connPropsStr)
Enters the connection-information values to be sent when the client connects to the server.

Parameters:
userNameStr - the user name string to use.
passwordStr - the password string to use.
connPropsStr - the connection-information properties string to use.

setAcceptorRejectIDStr

public void setAcceptorRejectIDStr(java.lang.String accIDStr,
                                   java.lang.String reasonStr)
Sets the identifier for a QWServer 'Acceptor' that should be rejected when a connection attempt is made. This identifier is used by the QWRelayFeeder to determine if the connected server is its own QWServer.

Parameters:
accIDStr - the QWServer 'Acceptor' identifer to use, or null for none.
reasonStr - a message string describing the reason why the QWServer 'Acceptor' should be rejected.

startConnectViaHostInfo

public abstract void startConnectViaHostInfo(java.lang.String serverHostAddrStr,
                                             int serverHostPortNum,
                                             boolean showPopupFlag)
Starts a new thread that establishes a connection to a QWServer.

Parameters:
serverHostAddrStr - the host address used to locate the server.
serverHostPortNum - the port number used to locate the server.
showPopupFlag - true to force the connection status popup dialog to be shown.

startConnectViaHostInfo

public void startConnectViaHostInfo(java.lang.String serverHostAddrStr,
                                    int serverHostPortNum)
Starts a new thread that connects to the event channel via a connection to a QWServer.

Parameters:
serverHostAddrStr - the host address used to locate the server.
serverHostPortNum - the port number used to locate the server.

shutdownConnection

public abstract void shutdownConnection(boolean showPopupFlag)
Shuts down the connection and waits for the disconnect to complete or timeout.

Parameters:
showPopupFlag - true to force the connection status popup dialog to be shown.

disconnectClientServices

public void disconnectClientServices(boolean sepThreadFlag)
Disconnects this client from the server services.

Parameters:
sepThreadFlag - true to use a separate thread and enforce a one second timeout; false to use the calling thread.

disconnectClientServices

public void disconnectClientServices()
Disconnects this client from the server services. A separate thread is used and a one second timeout is enforced.


doDisconnectClientServices

protected abstract boolean doDisconnectClientServices()
Performs the work of disconnecting this client from the server services.

Returns:
true if successful; false if an error occurred.

getServerIDNameStr

public abstract java.lang.String getServerIDNameStr()
Returns the server ID name string (defined in the QWServer's configuration file).

Returns:
The server ID name string, or null if not available.

getServerRepHostAddrStr

public abstract java.lang.String getServerRepHostAddrStr()
Returns the host address reported by the server.

Returns:
The host address reported by the server, or null if not available.

getServerRevisionStr

public abstract java.lang.String getServerRevisionStr()
Returns the server revision string.

Returns:
The server revision string, or null if not available.

requestServerAliveMsg

public abstract void requestServerAliveMsg()
Requests that the server send an 'Alive' message immediately. This allows the connection to the event channel to be verified more quickly.


isReqServerMsgsAvailable

public abstract boolean isReqServerMsgsAvailable()
Returns an indicator of whether or not the 'requestMessages()' method is available via the 'QWServices' on the current server.

Returns:
true if the 'requestServerMessages()' method is available, false if not.

clearConnAttemptStartedFlag

public void clearConnAttemptStartedFlag()
Clears the connection-attempt-started flag. This flag is set when the connection thread starts up.


getConnAttemptStartedFlag

public boolean getConnAttemptStartedFlag()
Returns the connection-attempt-started flag. This flag is set when the connection thread starts up.

Returns:
The connection-attempt-started flag.

clearConnAttemptFailedFlag

public void clearConnAttemptFailedFlag()
Clears the connection-attempt-failed flag. This flag is set after a connection attempt has failed.


getConnAttemptFailedFlag

public boolean getConnAttemptFailedFlag()
Returns the connection-attempt-failed flag. This flag is set after a connection attempt has failed.

Returns:
The connection-attempt-failed flag.

clearConnAttemptRejectedFlag

public void clearConnAttemptRejectedFlag()
Clears the connection-attempt-rejected flag. This flag is set after a connection attempt was rejected (probably because of invalid login).


getConnAttemptRejectedFlag

public boolean getConnAttemptRejectedFlag()
Returns the connection-attempt-rejected flag. This flag is set after a connection attempt was rejected (probably because of invalid login).

Returns:
The connection-attempt-rejected flag.

requestServerMessages

public abstract java.lang.String requestServerMessages(long timeVal,
                                                       long msgNum,
                                                       java.lang.String hostMsgNumListStr)
Requests that messages newer or equal to the specified time value or later than the specified message number be returned from the server. If a 'hostMsgNumListStr' value is not given and a non-zero message number is given and the given time value matches then messages with message numbers greater than the given message number are returned; otherwise messages newer or equal to the specified time value are returned (within a tolerance value). If a 'hostMsgNumListStr' value is given then it is used with the QWServices "requestSourced...()" methods (and any given message number is ignored). An XML message containing the messages is returned, using the following format:
 [QWresend NumRequested="10"]
   [QWmessage ...] [/QWmessage]
   [QWmessage ...] [/QWmessage]
   ...
 [/QWresend]
 
(Substitute angle brackets for square brackets.) The number of messages that would be required to fill the request is returned in the "NumRequested" attribute. However, no more than the oldest 'maxResendNumMsgs' number of messages will be returned in any single call to this method (additional calls may be needed to fetch all of the desired messages).

Parameters:
timeVal - the time-generated value for message associated with the given message number, or the requested time value to be used (milliseconds since 1/1/1970).
msgNum - the message number to use, or 0 or none.
hostMsgNumListStr - a list of feeder-data-source host-name/message-number entries, or null or empty string if the "requestSourced...()" methods should not be used.
Returns:
An XML-formatted string containing the messages, or an empty string if an error occurs.

performClientStatusCheck

public abstract boolean performClientStatusCheck()
                                          throws java.lang.NoSuchMethodException,
                                                 QWAbstractConnector.StatusCheckFailedException
Calls the QWServices 'clientStatusCheck()' method.

Returns:
true if the an updated version of the client is available; false if not.
Throws:
java.lang.NoSuchMethodException - if the 'clientStatusCheck()' method is not implemented on the server.
QWAbstractConnector.StatusCheckFailedException - if the call to 'clientStatusCheck()' failed with an exception other than 'NoSuchMethodException'.

fetchClientUpgradeInfoFromServer

public abstract java.lang.String fetchClientUpgradeInfoFromServer()
Returns information about available client-program upgrades via the QWServices 'getClientUpgradeInfo()' method.

Returns:
An XML-formatted string containing information about available client-program upgrades, or null if an error occurred.

fetchRedirectedServerLoc

public abstract java.lang.String fetchRedirectedServerLoc()
Returns the location of the server that the client is being redirected to. The returned string may also be a comma-separated list of "hostAddr:portNum" entries.

Returns:
The redirect-server location string in the form "hostAddr:portNum", an empty string if the client is not being redirected, or null if an error occurred.

getInitializedFlag

public abstract boolean getInitializedFlag()
Returns the "initialized" status of the connection.

Returns:
true if the connection is initialized.

getConnectedFlag

public abstract boolean getConnectedFlag()
Returns the connection status. If 'invalidateConnection()' has been called then this method will return false until the connection is reinitialized.

Returns:
true if the connection is active, false if not.

invalidateConnection

public abstract void invalidateConnection()
Marks the connection as "invalidated", causing the 'getConnectedFlag()' method to return 'false'.


isStatusReportDataAvail

public abstract boolean isStatusReportDataAvail()
Determines if get-status-report methods are available on the server.

Returns:
true if get-status-report methods are available on the server; false if not.

getStatusReportTime

public abstract long getStatusReportTime()
Fetches the timestamp value for the latest status report from the server.

Returns:
The timestamp value for the latest status report from the server, or 0 if no report is available or if an error occurred.

getStatusReportData

public abstract java.lang.String getStatusReportData()
Fetches the latest status-report data from the server.

Returns:
A string containing the latest status-report data from the server, an empty string if no report is available, or null if an error occurred.

getDecodedStatusReport

public java.lang.String getDecodedStatusReport()
Fetches and decodes the latest status report from the server.

Returns:
A string containing the latest status report from the server, an empty string if no report is available, or null if an error occurred.

getServerIDString

public java.lang.String getServerIDString()
Returns an identification string for the connected server. This string is the server ID name (if available), or the host address and port number for the server.

Returns:
An identification string for the connected server, or an empty string if not available.

getDetailedServerIDString

public java.lang.String getDetailedServerIDString()
Returns a more-detailed identification string for the configured server. This string contains the server ID name and the "address: port" ID for the server.

Returns:
An identification string for the configured server, or an empty string if not available.

getCertificateFileDataArr

public byte[] getCertificateFileDataArr()
Returns the certificate-file data that was fetched from the server at connect time.

Returns:
The certificate-file data that was fetched from the server at connect time, or null if none was fetched.

getConnPanelObj

public ConnStatusInterface getConnPanelObj()
Returns the connection status interface object.

Returns:
An object that implements 'ConnStatusInterface', or null if none available.

setConnStatusRefocusComponent

public void setConnStatusRefocusComponent(java.lang.Object compObj)
Sets the component that is to receive focus after the connection status popup dialog is cleared.

Parameters:
compObj - the compoment to receive focus.

userRequestShowConnStatusPopupDialog

public void userRequestShowConnStatusPopupDialog()
Displays the popup dialog showing extra connection status information in response to a user request.


autoClearConnStatusPopupDialog

public void autoClearConnStatusPopupDialog()
Clears any displayed connection status popup dialog if the user has not requested that it be shown.


showConnPanelPopup

public void showConnPanelPopup()
Shows the popup dialog displaying extra status information for the connection status panel.


setConnPanelData

public void setConnPanelData(java.lang.String textStr,
                             java.lang.String popupStr,
                             int symColorIdx)
Sets the message strings for the connection status panel and popup, as well as the color for the symbol on the panel.

Parameters:
textStr - text for panel, or null for no change.
popupStr - text for popup, or null for no change.
symColorIdx - index of color for symbol (one of the ConnStatusInterface '..._COLOR_IDX' values), or 'NULL_COLOR_IDX' for no change.

setConnPanelData

public void setConnPanelData(java.lang.String textStr,
                             java.lang.String popupStr)
Sets the message strings for the connection status panel and popup.

Parameters:
textStr - text for panel, or null for no change.
popupStr - text for popup, or null for no change.

setConnPanelInitError

protected void setConnPanelInitError(java.lang.String popupTextStr,
                                     int logLevelVal)
Sets connection status panel to show an initialization error.

Parameters:
popupTextStr - message to show in the popup panel.
logLevelVal - log level for message sent to log file.

setConnPanelInitError

protected void setConnPanelInitError(java.lang.String popupTextStr)
Sets connection status panel to show an initialization error.

Parameters:
popupTextStr - message to show in the popup panel.