QWCorbaOutputter




Introduction

     QWCorbaOutputter is an outputter module for the QuakeWatch server that provides for the delivery of messages to any number of "subscribers" via CORBA methods.  The subscriber programs may be written in any programming language capable of communicating via CORBA methods.  The QWCorbaOutputter module will queue and resend messages when deliveries fail because of communications errors, and will persistently track message deliveries across instances of the QuakeWatch server and the subscribers.



Configuration File

     The settings for a QWCorbaOutputter are contained in a 'QWOutputterMod' element in the QuakeWatch server configuration file, "conf/QWServerConfig.xml".  A sample configuration file may be found in the "Example Configuration with QWCorbaOutputter" section.
     Note that when a QuakeWatch server is used solely for the delivery of messages to subscribers via a QWCorbaOutputter module, the Notification Service (CORBA-event-channel) and client QWServices are not needed.  Is this case, the Notification Service does not need to be started (via 'startNotif'/'runNotif.bat'), and these services may be "turned off" by setting "notifSvcPortNum = 0" and "qwServicesAvailFlag = false" in the QuakeWatch server configuration file.

The following settings for a QWCorbaOutputter are specified as attributes to a 'QWOutputterMod' element in the server configuration file:

Name = "feederName"
     The name associated with the outputter module.  The QWCorbaOutputter module is usually named "QWCorbaOutputter".

LogFileName = "logFileName"
     The log file to be used by the outputter module.  For the QWCorbaOutputter module, "log/QWCorbaOutputter.log" is usually used.  A date code in the form "_yyyymmdd" will be inserted into the name, and a new log file name will be used each day.  (If more than one outputter were to be specified, each outputter would need to have a separate log file.)  If no log file is specified then none will be created.

LogFileLevel = "level"
     The message level for the outputter's log file output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".

ConsoleLevel = "level"
     The message level for the feeder's console output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".

The following settings for a QWCorbaOutputter reside within a 'QWOutputterSettings' sub-element beneath the 'QWOutputterMod' element in the server configuration file:

outputPortNumber = ###
     The port number that subscribers will use to access to the QWCorbaOutputter.  If this parameter is not specified then the value will default to 36688.

maxMessageAgeHours = ###
     The maximum age, in hours, for messages delivered to subscribers.  Messages older than the specified age will be discarded.  This parameter may be specified as a floating point value (such as 1.5 hours), and specifying a value of 0.0 will result in no age limit.  If this parameter is not specified then the value will default to 24.0 hours.

maxMsgQueueCount = ###
     The maximum number of messages allowed to reside in the queue for any given subscriber.  When the number of messages in the queue is greater than or equal to this parameter and a new message arrives, the oldest message in the queue is removed.  If this parameter is set to zero then no maximum is enforced.  If this parameter is not specified then the value will default to 1000.

retryAfterFailDelaySecs = ###
     The number of seconds before a message is resent to a subscriber after the previous delivery attempt failed (usually due to communications errors).  If this parameter is not specified then the value will default to 20 seconds.

maximumRetryMinutes = ###
     The number of minutes before a subscriber is automatically disconnected due to all delivery attempts to the subscriber failing.  This parameter may be specified as a floating point value (such as 10.5 minutes).  If this parameter is not specified then the value will default to 10 minutes.
     After a subscriber is disconnected, all delivery attempts to the subscriber will cease and the subscriber's invocation of the 'checkConnection()' method will result in a CORBA-exception error.  If the subscriber (using the same name) later reestablishes a connection to the QWCorbaOutputter, the missed messages will delivered (as long as they are not older than the 'maxMessageAgeHours' limit and the 'maxMsgQueueCount' limit has not been exceeded).

unpackQWMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<QWmessage>" element of the received message.  All messages in the QuakeWatch system contain the message data inside of a "<DataMessage>" element surrounded by a "<QWmessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the child-elements of the "<QWmessage>" element being delivered.  If this parameter is not specified then the value will default to 'true'.  If the "unpackQWMessageFlag" parameter is 'false' then the "unpackDataMessageFlag" and "unpackEQMessageFlag" parameters will be ignored.

unpackDataMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<DataMessage>" element of the received message.  All messages in the QuakeWatch system contain the message data inside of a "<DataMessage>" element surrounded by a "<QWmessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the child-elements of the "<DataMessage>" element being delivered.  If this parameter is not specified then the value will default to 'true'.  If the "unpackQWMessageFlag" parameter is 'false' then the "unpackDataMessageFlag" parameter will be ignored.

unpackEQMessageFlag = true/false
     Set 'true' to "unpack" the contents of the "<EQMessage>" element of the received message (if found).  Messages in the ANSS-EQ-XML format will contain an "<Event>" element surrounded by an "<EQMessage>" element.  If this flag is 'true' then the message data is "unpacked", resulting in the "<Event>" element being delivered (the other child-elements of the "<EQMessage>" element are not included).  If this parameter is not specified then the value will default to 'false'.  If the "unpackQWMessageFlag" or "unpackDataMessageFlag" parameter is 'false' then the "unpackEQMessageFlag" parameter will be ignored.

subscribeAllDefaultFlag = true/false
     If 'true' and a given subscriber's subscription list is empty then all messages will be delivered to the subscriber. 
If 'false' and a given subscriber's subscription list is empty then no messages will be delivered to the subscriber.  If this parameter is not specified then the value will default to 'false'.  See the Subscriber IDLs section for more information.

trackingDataDir = "path"
     Sets the name of the directory used for subscriber message-tracking files. 
If this parameter is not specified then the value will default to "outputterdata".



Subscriber IDLs

     A subscriber establishes a connection to the QWCorbaOutputter via the methods defined in the "idl/QWSubscription.idl" file.  The 'connectPushSubscriber()' method is used to connect a subscriber such that all messages are delivered; the 'connectPushSubscriberTo()' method is used to connect such that only messages whose domain and channel values match those in the given 'domainChanBlkArr' list are delivered. (See below for more information about domain/channel subscription.)  In either case, a unique subscriber name must be provided, as well as a 'subServicesHolder' object that will be loaded with a 'QWPushSubServices' object, as defined by the "idl/QWPushSubServices.idl" file.
     The subscriber may then use the 'QWPushSubServices' methods to interact with the QWCorbaOutputter.  The subscriber should create a 'QWRecMsgCallBack' object and use the 'connectRecMsgCallBack()' method to pass that object to the QWCorbaOutputter.  This will setup a "push" call-back where the QWCorbaOutputter will invoke the 'receiveMessage()' method on the
'QWRecMsgCallBack' object whenever a new message is to be delivered to the subscriber.
     Subscribers may use the 'setCallBackEnabled()' to temporarily disable the delivery of messages, and then re-enable when ready to receive them.  A subscriber may also return 'false' via the 'receiveMessage()' method to disable delivery.  Subscribers should call the 'checkConnection()' method periodically to verify the connection, and reestablish the connection if the call fails.  The 'disconnectSubscriber()' method should be called before a subscriber terminates its operation.
     A subscriber may register to receive only messages whose domain and channel values match those in its subscription list.  The subscription list may be provided via the QWSubscription 'connectPushSubscriberTo()' method, or it may be modified via the 'subscribe()' and 'unsubscribe()' methods.  If the 'domainStr' or 'channelStr' value is set to an empty string ("") or to the asterisk character ("*"), this will translate to mean "match all".  Note that whenever the subscription list is empty, no messages will be delivered to the subscriber if the 'subscribeAllDefaultFlag' configuration parameter is 'true' and all
messages will be delivered if 'subscribeAllDefaultFlag' is 'false'.
     A sample subscriber program, 'com.isti.quakewatch.server.test.QWSubscriberDemo', is included with the QuakeWatch server and may be used as a reference.



Example Configuration with QWCorbaOutputter

<QWServerConfig>
  <Settings>
      # ID name string for this QuakeWatch server:
    serverIdName = "QWCorbaOutputter Test Server"
      # Name of console output redirect file:
    consoleRedirectFileName = "log/QWServerConsole.txt"
      # Name of the log file:
    serverLogFileName = "log/QWServer.log"
      # Level of log messages sent to the log file:
    serverLogFileLevel = "Debug"
      # Level of log messages sent to the console:
    serverConsoleLevel = "Info"
      # Maximum age for log files (days, 0=infinite):
    logFilesMaxAgeInDays = 30
      # Port number spec for this server:
    serverPortNum = 39977
      # Port # spec for notification service (0 = not used):
    notifSvcPortNum = 0
      # false to disable QWServices for client connections:
    qwServicesAvailFlag = false
      # alternate server IDs list:
    altServerIdsList = ""
      # maximum message size (0 = no limit):
#    maximumMessageSize = 65536
      # true = use numberic IPs instead of host names:
#     publishNumericIPFlag = false
  </Settings>
  <QWFeederMod
     Name = "QWRelay"
     Class = "com.isti.quakewatch.server.QWRelayFeeder"
     LogFileName = "log/QWRelayFeeder.log"
     LogFileLevel = "Debug"
     ConsoleLevel = "Warning">
     <QWFeederSettings>
         # host address of server for QWRelay feeder:
       serverHostAddress = "quakewatch1.cisn.org"
         # port number of server for QWRelay feeder:
       serverPortNumber = 39977
         # true for QW web services server
       webServicesServerFlag = false
         # max event from server age (days):
#       maxServerEventAgeDays = 3.0
         # list of alternate servers for fail-over reconnect:
       alternateServersList = "quakewatch2.cisn.org:39977,quakewatch3.cisn.org:39977,quakewatch4.cisn.org:39977"
         # true = enable fail-over reconnect to alternate servers:
       altServersEnabledFlag = true
         # true = allow only default alternate servers:
       keepDefaultAltServersFlag = false
     </QWFeederSettings>
  </QWFeederMod>
  <QWOutputterMod
     Name = "QWCorbaOutputter"
     Class = "com.isti.quakewatch.server.outputter.QWCorbaOutputter"
     LogFileName = "log/QWCorbaOutputter.log"
     LogFileLevel = "Debug"
     ConsoleLevel = "Info">
     <QWOutputterSettings>
         # port number for this outputter to listen on:
       outputPortNumber = 36688
         # maximum age for delivered messages (hours, 0.0 = no limit):
       maxMessageAgeHours = 24.0
         # maximum number of queued messages (0 = no limit):
       maxMsgQueueCount = 1000
         # seconds before retry after delivery failure to subscriber:
       retryAfterFailDelaySecs = 20
         # max retry time before disconnect (minutes, 0.0 = no limit):
       maximumRetryMinutes = 10.0
         # unpack message from 'QWmessage' element:
       unpackQWMessageFlag = true
         # unpack message from 'DataMessage' element:
       unpackDataMessageFlag = true
         # unpack message from 'EQMessage' element:
       unpackEQMessageFlag = false
     </QWOutputterSettings>
  </QWOutputterMod>
</QWServerConfig>



10/9/2009 - Eric Thomas, Instrumental Software Technologies, Inc. - info@isti.com