Migrating To PDL Java Client Version 3

« Back to user guide

Overview

As of July 2025, the U.S. Geological Survey’s (USGS) Hazards Development Team (HazDev) has released an updated version of the PDL Java Client to migrate on-premises Hubs (located at prod01-pdl01.cr.usgs.gov and prod02-pdl01.cr.usgs.gov) to the cloud.

The on-premises Hubs are scheduled for decommission by October 1st 2025, at which point collaborators sending products for events within the past 30 days will need to send/receive products to/from the new cloud PDL Hub. Product submissions for events older than 30 days should continue to be sent directly to ComCat.

Please review the migration guide below for required actions and more detailed instructions about what you need to do.

During this migration, please email any questions/comments to gs-haz_dev_team_group@usgs.gov.

Required actions

All collaborators are required to use the new PDL Java Client, and are able to start migrating to it in July 2025.

Receivers

Starting August 12th, 2025, receivers can begin receiving products from the new Realtime Cloud Hub using a PDL Java Client 3.5.1 or greater.

If you have previously updated the PDL Java Client to version 3.5.0, it is imperative to use the PDL Java Client version 3.5.1 or greater when receiving products from the new Cloud Realtime Hub to ensure you receive all products. If you have previously updated to version 3.5.0, update to version 3.5.1 by replacing the jar file and update the configuration as documented below to receive from the new Realtime Cloud Hub.

Using an AwsProductReceiver

To receive product notifications from the new Realtime Cloud Hub an AwsProductReceiver must be used, refer to aws-product-receiver or follow the example below to add an AwsProductReceiver section with the included products_created_after subsection.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

receivers = aws_product_receiver

# An example configuration of an AwsProductReceiver
[aws_product_receiver]
type = gov.usgs.earthquake.aws.AwsProductReceiver
indexFile = receiver_index.db
storage = receiver_storage
# Parameters below are specific to an AwsProductReceiver
# Where productsCreatedAfterClient references the products_created_after_client subsection
productsCreatedAfterClient = products_created_after_client
initialCatchUpAge = 2
anyMessageInterval = 480000
trackingFileName = receiver_tracking.db
# URL specific to the new Realtime Cloud PDL Hub
url = wss://earthquake.usgs.gov/pdl/east/products/notifications/subscribe

[receiver_storage]
type = gov.usgs.earthquake.aws.JsonProductStorage
table = receiver_storage

[products_created_after_client]
type = gov.usgs.earthquake.aws.ProductsCreatedAfterClient
batchLimit = 50
maxRetryAttempts = 5
# URL template specific to the new Realtime Cloud PDL Hub
urlTemplate = https://earthquake.usgs.gov/pdl/east/products/notifications?broadcastafter={CREATED_AFTER}&limit={BATCH_LIMIT}

Using an EIDSNotificationReceiver

This class has been marked as deprecated in the newest PDL Java Client, but functionality will continue to work. With the update to Java 17, the following add-opens flag must be added to the Java command in order for an EIDSNotificationReceiver to continue to work. See eids-product-receiver for a full configuration example.

1

java --add-opens java.base/java.lang=ALL-UNNAMED -jar ProductClient.jar --receive

Senders

The on-premises Hubs are scheduled to be decommissioned October 1st 2025, but are still available and the recommended location to send products to. At this time, no change is needed in the location to which products are sent. However, some configuration changes may be required depending on the type of sender you are using. See below for details.

By early September 2025, we will provide steps for sending products to the new Realtime Cloud PDL Hub.
A separate communication email will be sent out for the steps needed to take.

Using a SocketProductSender sending to the on-premises PDL Hubs

When updating the PDL Java Client there are no configuration changes required to send to these hubs using a SocketProductSender.

Using an AwsProductSender sending to ComCat

In the new PDL Java Client there has been a breaking change added to the configuration for the AwsProductSender to send to ComCat. See the AwsProductSender documentation page for an example of configuring a [comcat_sender], and below for changing from version 2 to version 3.

Configuration (version <=2.9.2)
1
2
3
4
5
6
7

senders = comcat_sender

[comcat_sender]
type = gov.usgs.earthquake.aws.AwsProductSender
url = https://earthquake.usgs.gov/pdl/west/
privateKey = ./private-key
signProducts = true
New configuration (version >= 3.5.0)
1
2
3
4
5
6
7
8
9
10
11
12
13

senders = comcat_sender

[comcat_sender]
type = gov.usgs.earthquake.aws.AwsProductSender
# The url does not contain the path, that is now configured externally below
url = https://earthquake.usgs.gov
privateKey = ./product-key
signProducts = true
# The following parameters are now required to configure sending to ComCat
sendProductPath = /pdl/west/send_product
getUploadUrlsPath = /pdl/west/get_upload_urls
# Sending to ComCat requires products to be sent with contents in an ARRAY format
contentFormat = ARRAY

Using an EIDSInputWedge configuration

An EIDSInputWedge was used as a polling interface for sending new products. Messages to be sent were written to a poll directory and then converted to products by a parsing class that understood the file format.

This functionality has been migrated to a more configurable InputWedge class. While the EIDSInputWedge class exists in this version of the PDL Java Client, it is marked as deprecated and the InputWedge class should be used.

Configuration (version <=2.9.2)
1
2
3
4
5
6
7
8
9
10
11
12
13

mainclass = gov.usgs.earthquake.eids.EIDSInputWedge
directory = polldir
errordir = errordir
interval = 1000
senders = sender_prod1

loglevel = CONFIG

[sender_prod1]
type = gov.usgs.earthquake.distribution.SocketProductSender
host = prod01-pdl01.cr.usgs.gov
port = 11235
writeTimeout = 15000
New configuration (version >= 3.5.0)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# New mainclass entry point
mainclass = gov.usgs.earthquake.distribution.InputWedge
# New configurable poller class
poller = directory_poller
senders = sender_prod1

loglevel = CONFIG

# New configurable poller class implementation
[directory_poller]
type = gov.usgs.util.DirectoryPoller
pollDirectory = pollDirectory
oldInputDirectory = oldInputDirectory
errorDirectory = errorDirectory
interval = 1000
pollCarefully = true

[sender_prod1]
type = gov.usgs.earthquake.distribution.SocketProductSender
host = dev01-pdl01.cr.usgs.gov
port = 11235
writeTimeout = 15000

Relaying

The recommended way to relay products between hubs is to use a RelayProductListener. In the new PDL Java Client there has been a breaking change to the RelayProductListener to use a senders property in its configuration. This allows multiple senders to be configured on the relay. An example configuration of this can be found in relay-product-listener and below for changing from version 2 to version 3.

Configuration (version <=2.9.2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

listeners = relay_listener

[relay_listener]
type = gov.usgs.earthquake.distribution.RelayProductListener
listenerIndex = listener_index
# This configuration parameter was optional in version 2
senderType = aws
# The configuration for the type of sender specified by `senderType` was configured inline
url = https://earthquake.usgs.gov/pdl/west/
maxTries = 3
retryDelay = 30000
timeout = 300000

[listener_index]
type = gov.usgs.earthquake.aws.JsonNotificationIndex
table = listener_index
New configuration (version >= 3.5.0)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

listeners = relay_listener

[relay_listener]
type = gov.usgs.earthquake.distribution.RelayProductListener
listenerIndex = listener_index
# In version 3 there is a list of senders that are configured in subsequent sections
senders = sender_prod01, sender_prod02

# Configured sender from the [relay_listener] section
[sender_prod01]
type = gov.usgs.earthquake.distribution.SocketProductSender
host = prod01-pdl01.cr.usgs.gov
port = 11235

# Configured sender from the [relay_listener] section
[sender_prod02]
type = gov.usgs.earthquake.distribution.SocketProductSender
host = prod02-pdl01.cr.usgs.gov
port = 11235

[listener_index]
type = gov.usgs.earthquake.aws.JsonNotificationIndex
table = listener_index

With the addition of the new InputWedge class, another possibility to relay products can be found in relaying.
The example provided shows a setup of using an InputWedge and Receiver combination to relay products.

Common troubleshooting tips

If you have any issues, refer to the migration troubleshooting page to find solutions for common issues, and please email any questions to gs-haz_dev_team_group@usgs.gov.

Last modified: Wed Aug 13 18:27:01 UTC 2025