com.isti.quakewatch.util
Interface QWWebSvcsInterface

All Superinterfaces:
ErrorMsgMgrIntf

public interface QWWebSvcsInterface
extends ErrorMsgMgrIntf

Interface QWWebSvcsInterface defines methods for interacting with a QuakeWatch Web Services Server.


Method Summary
 java.lang.Boolean clientStatusCheck(java.lang.String clientInfoStr)
          Determines the client-version status.
 boolean connect(java.lang.String hostNameStr, int hostPortNum, LogFile logObj)
          Establishes a connection to a QuakeWatch Web Services Server and verifies that the server is reachable and running.
 boolean connect(java.lang.String hostNameStr, int hostPortNum, LogFile logObj, java.lang.String usernameStr, java.lang.String passwordStr)
          Establishes a connection to a QuakeWatch Web Services Server and verifies that the server is reachable and running.
 void disconnect()
          Closes the connection to the QuakeWatch Web Services Server.
 java.lang.Boolean disconnectClient(java.lang.String clientInfoStr)
          Disconnects the client connection.
 java.lang.String getAcceptorIDStr()
          Returns an identifier string that uniquely identifies the server.
 java.lang.String getAltServersIdsListStr()
          Fetches the list of alternate web service server IDs (defined in the QWServer's configuration file).
 byte[] getCertificateFileData()
          Fetches a byte-array of certificate-file data from the QWServer.
 java.lang.String getClientUpgradeInfo(java.lang.String clientInfoStr)
          Returns information about available client-program upgrades.
 boolean getConnInvalidLoginFlag()
          Determines if the last connect attempt was rejected due to invalid login.
 java.net.URL getEndpointUrlObj()
          Returns the endpoint URL for the current connection.
 java.lang.String getRecommendedPollingInterval()
          Returns the recommended polling interval time for web-services clients, in milliseconds.
 boolean getRedirectedEndpointFlag()
          Returns an indicator of whether or not the current connection was redirected (by the server) to a different endpoint.
 java.lang.String getRedirectedEndpointUrlStr()
          Returns the URL string for the endpoint that the connection was redirected to (by the server), if any.
 java.lang.String getServerCacheSummary()
          Returns a string of information property values for the QWServer's cache and the server itself.
 java.lang.String getServerHostAddrStr()
          Fetches the server host address string for the QWServer.
 java.lang.String getServerIdNameStr()
          Fetches the server ID name string (defined in the QWServer's configuration file).
 java.lang.String getServerRevisionString()
          Returns the revision string for the QuakeWatch server.
 java.lang.String getStatusReportData()
          Fetches the latest status-report data from the QWServer.
 long getStatusReportTime()
          Fetches the timestamp value for the latest status report from the QWServer.
 java.lang.String getWebServiceVersion()
          Returns the web services version string.
 boolean isConnected()
          Returns a flag indicating whether or not the connection is active.
 java.lang.String requestFilteredMessages(long timeVal, long msgNum, java.lang.String domainTypeListStr)
          Requests that messages newer or equal to the specified time value or later than the specified message number be returned.
 java.lang.String requestMessages(long timeVal, long msgNum)
          Requests that messages newer or equal to the specified time value or later than the specified message number be returned.
 java.lang.String requestSourcedMsgsStr(long requestTimeVal, java.lang.String hostMsgNumListStr, java.lang.String domainTypeListStr)
          Requests that messages corresponding to the given time value and list of feeder-data-source host-name/message-number entries be returned.
 
Methods inherited from interface com.isti.util.ErrorMsgMgrIntf
clearErrorMessageString, clearFetchedErrorMessage, getErrorMessageFlag, getErrorMessageString, getUnfetchedMessageFlag
 

Method Detail

connect

boolean connect(java.lang.String hostNameStr,
                int hostPortNum,
                LogFile logObj,
                java.lang.String usernameStr,
                java.lang.String passwordStr)
Establishes a connection to a QuakeWatch Web Services Server and verifies that the server is reachable and running.

Parameters:
hostNameStr - host name to use, or null for default value ("localhost").
hostPortNum - host port number to use, or 0 for default value (8080).
logObj - log file object to use, or null for none.
usernameStr - username string to use, or null for none.
passwordStr - password string to use, or null for none.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

connect

boolean connect(java.lang.String hostNameStr,
                int hostPortNum,
                LogFile logObj)
Establishes a connection to a QuakeWatch Web Services Server and verifies that the server is reachable and running.

Parameters:
hostNameStr - host name to use, or null for default value ("localhost").
hostPortNum - host port number to use, or 0 for default value (8080).
logObj - log file object to use, or null for none.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

disconnect

void disconnect()
Closes the connection to the QuakeWatch Web Services Server.


isConnected

boolean isConnected()
Returns a flag indicating whether or not the connection is active.

Returns:
true if connected; false is not.

getAcceptorIDStr

java.lang.String getAcceptorIDStr()
Returns an identifier string that uniquely identifies the server. This identifier is used by the QWRelayFeeder to determine if the connected server is its own QWServer.

Returns:
An identifier string that uniquely identifies the server.

getAltServersIdsListStr

java.lang.String getAltServersIdsListStr()
Fetches the list of alternate web service server IDs (defined in the QWServer's configuration file).

Returns:
The list of alternate server IDs, as a string in the form "hostAddr:portNum,hostAddr:portNum,...", or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getRecommendedPollingInterval

java.lang.String getRecommendedPollingInterval()
Returns the recommended polling interval time for web-services clients, in milliseconds.

Returns:
The recommended polling interval time, in milliseconds, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getServerCacheSummary

java.lang.String getServerCacheSummary()
Returns a string of information property values for the QWServer's cache and the server itself. The string will contain a set of comma-separated entries in the form: name="value". The names for the entries will come from the strings found in the 'ServerCacheInfoStrings' class.

Returns:
A string containing information property values, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getServerIdNameStr

java.lang.String getServerIdNameStr()
Fetches the server ID name string (defined in the QWServer's configuration file).

Returns:
The server ID name string, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getServerHostAddrStr

java.lang.String getServerHostAddrStr()
Fetches the server host address string for the QWServer.

Returns:
The server host address string, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getServerRevisionString

java.lang.String getServerRevisionString()
Returns the revision string for the QuakeWatch server.

Returns:
The revision string for the QuakeWatch server, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getWebServiceVersion

java.lang.String getWebServiceVersion()
Returns the web services version string.

Returns:
the web services version string, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getStatusReportTime

long getStatusReportTime()
Fetches the timestamp value for the latest status report from the QWServer.

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

getStatusReportData

java.lang.String getStatusReportData()
Fetches the latest status-report data from the QWServer.

Returns:
A string containing the latest status-report data from the QWServer, an empty string if no report is available, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getCertificateFileData

byte[] getCertificateFileData()
Fetches a byte-array of certificate-file data from the QWServer.

Returns:
A byte-array of certificate-file data, a zero-length array if no data is available, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

clientStatusCheck

java.lang.Boolean clientStatusCheck(java.lang.String clientInfoStr)
Determines the client-version status. Clients should call this method on a periodic basis while they are connected.

Parameters:
clientInfoStr - the client-connection-information properties string to use.
Returns:
A 'Boolean' object set to true if the an updated version of the client is available, a 'Boolean' object set to false if not, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getClientUpgradeInfo

java.lang.String getClientUpgradeInfo(java.lang.String clientInfoStr)
Returns information about available client-program upgrades.

Parameters:
clientInfoStr - the client-connection-information properties string to use.
Returns:
An XML-formatted string containing information about available client-program upgrades, an empty string if a clients manager is not available, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

disconnectClient

java.lang.Boolean disconnectClient(java.lang.String clientInfoStr)
Disconnects the client connection.

Parameters:
clientInfoStr - the client-connection-information properties string for the client.
Returns:
A 'Boolean' object set to true if the client was removed successfully; a 'Boolean' object set to false if no matching client entry was found, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

requestMessages

java.lang.String requestMessages(long timeVal,
                                 long msgNum)
Requests that messages newer or equal to the specified time value or later than the specified message number be returned. If 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). An XML message containing the messages is built and 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.
Returns:
An XML-formatted string containing the messages, an empty string if a server-side error occurred, or 'null' if a client-side error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

requestFilteredMessages

java.lang.String requestFilteredMessages(long timeVal,
                                         long msgNum,
                                         java.lang.String domainTypeListStr)
Requests that messages newer or equal to the specified time value or later than the specified message number be returned. If 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). Only messages whose event domain and type names match the given list of domain and type names will be returned (unless the given list is an empty string). An XML message containing the messages is built and 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.
domainTypeListStr - a list string of event domain and type names in the format "domain:type,domain:type...", where occurrences of the ':' and ',' characters not meant as separators may be "quoted" by preceding them with the backslash ('\') character and list items missing the ':' character will be considered to specify only a domain name (the type name will be an empty string); or an empty string for none.
Returns:
An XML-formatted string containing the messages, an empty string if a server-side error occurred, or 'null' if a client-side error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

requestSourcedMsgsStr

java.lang.String requestSourcedMsgsStr(long requestTimeVal,
                                       java.lang.String hostMsgNumListStr,
                                       java.lang.String domainTypeListStr)
Requests that messages corresponding to the given time value and list of feeder-data-source host-name/message-number entries be returned. If a list of domain and type names is given then only messages whose event domain and type names match the given list will be returned. An XML message containing the messages is built and 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:
requestTimeVal - 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).
hostMsgNumListStr - a list of feeder-data-source host-name/message-number entries in the form: "hostName"=msgNum,...
domainTypeListStr - a list string of event domain and type names in the format "domain:type,domain:type...", where occurrences of the ':' and ',' characters not meant as separators may be "quoted" by preceding them with the backslash ('\') character and list items missing the ':' character will be considered to specify only a domain name (the type name will be an empty string); null or an empty string for none.
Returns:
An XML-formatted string containing the messages, an empty string if a server-side error occurred, or 'null' if a client-side error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getConnInvalidLoginFlag

boolean getConnInvalidLoginFlag()
Determines if the last connect attempt was rejected due to invalid login.

Returns:
true if last connect attempt was rejected due to invalid login; false if not.

getEndpointUrlObj

java.net.URL getEndpointUrlObj()
Returns the endpoint URL for the current connection. The endpoint will be different from the original one specified if the connection has been redirected.

Returns:
The URL object specifying the endpoint for the current connection, or null if no connection is active.

getRedirectedEndpointFlag

boolean getRedirectedEndpointFlag()
Returns an indicator of whether or not the current connection was redirected (by the server) to a different endpoint.

Returns:
true if the connection was redirected; false if not.

getRedirectedEndpointUrlStr

java.lang.String getRedirectedEndpointUrlStr()
Returns the URL string for the endpoint that the connection was redirected to (by the server), if any.

Returns:
The URL string for the endpoint that the connection was redirected to (by the server), or null if the connection has not been redirected.