Receiving Products

« Back to User Guide

$Id: receiving.html 19872 2013-07-30 18:45:46Z jmfee $
$URL: https://ghttrac.cr.usgs.gov/websvn/ProductDistribution/trunk/etc/documentation/userguide/receiving.html $

Navigation

Configuring a Listener

To configure an external notification listener, or an external indexer listener, follow the steps below:

  1. Open the config.ini file in the bin subdirectory of your ProductClient installation path. (bin/config.ini)
  2. Add a new section with a unique name, placing the section name in square braces "[]". By convention, the suffix "_exec" is added for a section defining an external listener.
  3. Under this section you should first define the type of listener interface that is expected by the external process, either gov.usgs.earthquake.distribution.ExternalNotificationListener or gov.usgs.earthquake.distribution.ExternalIndexerListener
  4. You should then define all of the configuration arguments for the type of listener selected.

    The storage argument for listeners should be set to a section name in this config.ini that sets the storage parameters, not specifically to a storage type itself.

    Note: Listeners cannot share the same storage configuration.

  5. To configure a new storage object for a listener, create a new section of the config.ini file. By convention, the suffix "_storage" is added for a section defining a storage object. The storage section definition for external listeners should always have a type value of gov.usgs.earthquake.distribution.FileProductStorage, and the path should be the absolute path to the desired root storage directory for the received products.
  6. When both sections are complete, the section name for the listener should be added to the listeners value in the config.ini file, separated by commas.
  7. After editing the config.ini file, restart the ProductClient to load the new configuration settings.

Config Example

listeners = losspager_exec

[losspager_exec]
type=gov.usgs.earthquake.distribution.ExternalNotificationListener
command=/home/www/apps/LossPager/indexer/lossindex.py
storage=losspager_storage
includeTypes=losspager

[losspager_storage]
type=gov.usgs.earthquake.distribution.FileProductStorage
directory=/home/www/data/LossPager/products

ExternalNotificationListener Arguments

Configuration Arguments

command
(Required) The command to execute. This must be an executable command and may include arguments. Any product specific arguments are appended at the end of command.
storage
(Required) A directory used to store all products. Each product is extracted into a separate directory within this directory and is referenced by the --directory=/path/to/directory argument when command is executed.
timeout
(Optional, Default = 100000 = 100 seconds) The command timeout in milliseconds. If timeout is less than zero, the process will be allowed to run indefinitely.
includeTypes
(Optional) This should be a comma-separated list of product types to specifically use to trigger this command. Product types not included in this list will not be sent to this listener. If this is not defined, the listener will receive all products not specifically excluded with the configuration below.
excludeTypes
(Optional) this should be a comma-separated list of product types that specifically should not be sent to this listener. Product types included in this list will not be sent to this listener.

Outgoing Arguments

--directory=[/path/to/file]
An absolute path to where product data is stored related to this notification.
--type=[type]
The type of product associated with this notification.
--code=[code]
The product code, without source network, for the product associated with this notification.
--source=[source]
The source network for the product associated with this notification.
--updateTime=[time]
The update time of the product associated with this notification in standard XML date format. (e.g. 2000-01-01T00:00:00Z)
--status=[status]
The status of the product related to this notification. It can be any of the following:
UPDATE
The product has been created or updates an existing product.
DELETE
The product has been marked to be deleted.
--delete
(Optional) This argument will appear only when the value of the --status argument is "DELETE".
--trackerURL=[url]
(Optional) The location for the tracker for this product in product distribution.
"--property-[name]=[value]"
(Optional) A series of these arguments will be appended, one for each defined property in the summary of this product.
"--link-[relation]=[value]"
(Optional) A series of these arguments will be appended, one for each defined link in the summary of this product.
--content
(Optional) Indicates that non-file content will be sent to the command over its stdin.
--contentType=[type]
(Optional) Indicates the MIME type of the content that will be sent over stdin. Will always appear when the --content argument appears.
--signature=[signature]
(Optional) The signature key of the product creator, if it was provided.

ExternalIndexerListener Arguments

All arguments for the ExternalNotificationListener are used and included with the following additional arguments.
processDuplicateProducts
(Optional, default=false) Will process duplicate products if the value is "true".
processPreferredOnly
(Optional, default=false) Will process only the preferred product of this type for a given event at the time notification is received if the value is "true".

Outgoing Arguments

--action=[action]
The change related to this indexer event. It may be any one of the following values:
EVENT_ADDED
A new event has been added to the index.
EVENT_UPDATED
The indexed event has been updated.
EVENT_DELETED
The indexed event has been deleted.
EVENT_ARCHIVED
The indexed event has been archived.
PRODUCT_ADDED
A new product was added that is not currently associated to an event.
PRODUCT_UPDATED
A product that is not currently associated to an event has been updated.
PRODUCT_DELETED
A product that is not currently associated to an event has been deleted.
PRODUCT_ARCHIVED
A product that is not currently associated to an event has been archived.
--eventids=[ids]
(Optional) The known event IDs associated with the indexer event. These will include the event IDs separated by commas. This argument will not appear on a product not associated to an event.
--preferred-eventid=[id]
(Optional) The preferred event ID associated with this indexer event. This will be the event source network followed by the source's assigned code. This argument will not appear on a product not associated to an event.
--preferred-magnitude=[magnitude]
(Optional) The preferred magnitude associated with the event received. This argument will not appear on a product not associated to an event.
--preferred-longitude=[longitude]
(Optional) The preferred longitude associated with the event received. This argument will not appear on a product not associated to an event.
--preferred-latitude=[latitude]
(Optional) The preferred latitude associated with the event received. This argument will not appear on a product not associated to an event.
--preferred-depth=[depth]
(Optional) The preferred depth associated with the event received. This argument will not appear on a product not associated to an event.
--preferred-eventtime=[time]
(Optional) The preferred origin time associated with the event received. This argument will not appear on a product not associated to an event.