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>
8/26/2019 - Kevin Frechette, Instrumental Software Technologies, Inc.
- info@isti.com