Package gov.usgs.earthquake.distribution

Class JDBCNotificationIndex

java.lang.Object

gov.usgs.util.DefaultConfigurable

gov.usgs.earthquake.util.JDBCConnection

gov.usgs.earthquake.distribution.JDBCNotificationIndex

All Implemented Interfaces:

NotificationIndex, Configurable, java.lang.AutoCloseable

public class JDBCNotificationIndex
extends JDBCConnection
implements NotificationIndex

Stores and retrieves Notifications. This is typically used by a NotificationReceiver to track its Notifications, but may also be used by NotificationListeners. Each object should maintain a separate NotificationIndex. This implementation uses a SQLite Database as the index.

See Also:

NotificationIndex

Field Summary

Fields

Modifier and Type	Field	Description
protected static java.lang.String	JDBC_FILE_PROPERTY	This is the property key used in the configuration file to specify a different SQLite database file.

Constructor Summary

Constructors

Constructor	Description
JDBCNotificationIndex()	Default, no-arg constructor.
JDBCNotificationIndex(Config config)	Constructor called from the config object conforming to the Configurable interface specification.
JDBCNotificationIndex(java.lang.String filename)	Constructor call from filename, where filename is jdbc index file If null, then index file defaults

Method Summary

Modifier and Type	Method	Description
void	addNotification(Notification notification)	Add a notification to the index.
void	configure(Config config)	Reads the given config object and sets values appropriately.
protected java.sql.Connection	connect()	Connect to the database.
java.util.List<Notification>	findExpiredNotifications()	Search the index for expired notifications.
java.util.List<Notification>	findNotifications(ProductId id)	Search the index for notifications matching id.
java.util.List<Notification>	findNotifications(java.lang.String source, java.lang.String type, java.lang.String code)	Search the index for notifications matching the sources, types, and codes.
java.util.List<Notification>	findNotifications(java.util.List<java.lang.String> sources, java.util.List<java.lang.String> types, java.util.List<java.lang.String> codes)	Search the index for notifications matching the sources, types, and codes.
protected java.sql.PreparedStatement	getCorrectStatement(java.util.List<java.lang.String> sources, java.util.List<java.lang.String> types, java.util.List<java.lang.String> codes)
protected java.util.List<Notification>	getNotifications(java.sql.PreparedStatement ps)	Executes a prepared statement and parses the result set into a list of notifications.
protected Notification	parseNotification(java.lang.String source, java.lang.String type, java.lang.String code, java.sql.Date update, java.sql.Date expires, java.lang.String tracker, java.lang.String download)	Creates and returns a Notification based on the provided data.
void	removeNotification(Notification notification)	Remove a notification from the index.
void	removeNotifications(java.util.List<Notification> notifications)	Remove notifications from the index.
void	shutdown()	Closes the JDBC connection and all it's associated prepared statements.
void	startup()	Connects to the JDBC DB index and prepares the DML/Query statements that will execute at runtime.

Methods inherited from class gov.usgs.earthquake.util.JDBCConnection

beginTransaction, close, commitTransaction, getConnection, getDriver, getUrl, rollbackTransaction, setDriver, setUrl, verifyConnection

Methods inherited from class gov.usgs.util.DefaultConfigurable

getName, setName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface gov.usgs.util.Configurable

getName, setName

Field Detail

JDBC_FILE_PROPERTY

protected static final java.lang.String JDBC_FILE_PROPERTY

This is the property key used in the configuration file to specify a different SQLite database file. If this file doesn't exist it will be created at startup time

See Also:

Constant Field Values

Constructor Detail

JDBCNotificationIndex

public JDBCNotificationIndex()
                      throws java.lang.Exception

Default, no-arg constructor. This just ensures the JDBC SQLite driver is appropriately on the classpath for proper runtime execution. This probably will not get called directly in favor of the configurable constructor.

Throws:

java.lang.Exception - If the JDBC driver class is not found.

See Also:

JDBC_DRIVER_CLASS

JDBCNotificationIndex

public JDBCNotificationIndex(java.lang.String filename)
                      throws java.lang.Exception

Constructor call from filename, where filename is jdbc index file If null, then index file defaults

Parameters:

filename - String - What will be the index file

Throws:

java.lang.Exception - if error occurs

JDBCNotificationIndex

public JDBCNotificationIndex(Config config)
                      throws java.lang.Exception

Constructor called from the config object conforming to the Configurable interface specification. This internally calls its no-arg constructor then configures itself.

Parameters:

config - The config object from which this instance will be configured.

Throws:

java.lang.Exception - If the JDBC driver class is not found.

See Also:

Configurable, JDBC_DRIVER_CLASS

Method Detail

configure

public void configure(Config config)
               throws java.lang.Exception

Reads the given config object and sets values appropriately.

Specified by:

configure in interface Configurable

Overrides:

configure in class JDBCConnection

Parameters:

config - The config object from which this instance will be configured.

Throws:

java.lang.Exception - Exception

See Also:

Configurable

connect

protected java.sql.Connection connect()
                               throws java.lang.Exception

Description copied from class: JDBCConnection

Connect to the database. Sub-classes determine how connection is made.

Overrides:

connect in class JDBCConnection

Returns:

the connection.

Throws:

java.lang.Exception - if unable to connect.

startup

public void startup()
             throws java.lang.Exception

Connects to the JDBC DB index and prepares the DML/Query statements that will execute at runtime. If the JDBC DB index file does not exist then an empty schema will be copied out of the executing JAR file to be used.

Specified by:

startup in interface Configurable

Overrides:

startup in class JDBCConnection

Throws:

java.lang.Exception - if error occurs

See Also:

Configurable

shutdown

public void shutdown()
              throws java.lang.Exception

Closes the JDBC connection and all it's associated prepared statements.

Specified by:

shutdown in interface Configurable

Overrides:

shutdown in class JDBCConnection

Throws:

java.lang.Exception - if error occurs

See Also:

Configurable

addNotification

public void addNotification(Notification notification)
                     throws java.lang.Exception

Add a notification to the index. If an identical notification is already in the index, the implementation may choose whether or not to store the duplicate information.

Specified by:

addNotification in interface NotificationIndex

Parameters:

notification - the notification to add.

Throws:

java.lang.Exception - if an error occurs while storing the notification.

See Also:

NotificationIndex

removeNotification

public void removeNotification(Notification notification)
                        throws java.lang.Exception

Remove a notification from the index. All matching notifications should be removed from the index.

Specified by:

removeNotification in interface NotificationIndex

Parameters:

notification - the notification to remove.

Throws:

java.lang.Exception - if an error occurs while removing the notification.

See Also:

NotificationIndex

removeNotifications

public void removeNotifications(java.util.List<Notification> notifications)
                         throws java.lang.Exception

Remove notifications from the index. All matching notifications should be removed from the index.

Specified by:

removeNotifications in interface NotificationIndex

Parameters:

notifications - the notifications to remove.

Throws:

java.lang.Exception - if an error occurs while removing the notifications.

See Also:

NotificationIndex

findNotifications

public java.util.List<Notification> findNotifications(ProductId id)
                                               throws java.lang.Exception

Search the index for notifications matching id. If more than one notification matches, all should be returned.

Specified by:

findNotifications in interface NotificationIndex

Parameters:

id - the ProductId to find.

Returns:

a list of matching notifications.

Throws:

java.lang.Exception - if an error occurs while searching the index.

See Also:

NotificationIndex

findNotifications

public java.util.List<Notification> findNotifications(java.lang.String source,
                                                      java.lang.String type,
                                                      java.lang.String code)
                                               throws java.lang.Exception

Search the index for notifications matching the sources, types, and codes. Only one notification for each unique ProductId (source+type+code+updateTime) should be returned. If sources, types, and/or codes are null, that parameter should be considered a wildcard. If sources, types, and codes are all null, a notification for each unique ProductId in the index should be returned.

Specified by:

findNotifications in interface NotificationIndex

Parameters:

source - sources to include, or all if null.

type - types to include, or all if null.

code - codes to include, or all if null.

Returns:

a list of matching notifications.

Throws:

java.lang.Exception - if an error occurs while searching the index.

See Also:

NotificationIndex

findNotifications

public java.util.List<Notification> findNotifications(java.util.List<java.lang.String> sources,
                                                      java.util.List<java.lang.String> types,
                                                      java.util.List<java.lang.String> codes)
                                               throws java.lang.Exception

Search the index for notifications matching the sources, types, and codes. Only one notification for each unique ProductId (source+type+code+updateTime) should be returned. If sources, types, and/or codes are null, that parameter should be considered a wildcard. If sources, types, and codes are all null, a notification for each unique ProductId in the index should be returned. This implementation require synchronization to prevent SQLExceptions caused by concurrent access. SQLite locks the database whenever there is an open ResultSet resource. So even read queries can end up causing SQL concurrent access problems.

Specified by:

findNotifications in interface NotificationIndex

Parameters:

sources - sources to include, or all if null.

types - types to include, or all if null.

codes - codes to include, or all if null.

Returns:

a list of matching notifications.

Throws:

java.lang.Exception - if an error occurs while searching the index.

findExpiredNotifications

public java.util.List<Notification> findExpiredNotifications()
                                                      throws java.lang.Exception

Search the index for expired notifications. All expired notifications, even if duplicate, should be returned.

Specified by:

findExpiredNotifications in interface NotificationIndex

Returns:

a list of expired notifications.

Throws:

java.lang.Exception - if an error occurs while searching the index.

See Also:

NotificationIndex

getNotifications

protected java.util.List<Notification> getNotifications(java.sql.PreparedStatement ps)
                                                 throws java.lang.Exception

Executes a prepared statement and parses the result set into a list of notifications. The prepared statement can have any set of criteria and all required parameters should be bound before calling this method. The result set of the prepared statement must include at least: - PRODUCT_SOURCE_COLUMN
- PRODUCT_TYPE_COLUMN
- PRODUCT_CODE_COLUMN
- PRODUCT_UPDATE_COLUMN
- EXPIRATION_DATE_COLUMN
- TRACKER_URL_COLUMN
- PRODUCT_URL_COLUMN

Parameters:

ps - The prepared statement to execute.

Returns:

A list of notifications returned by executing the statement.

Throws:

java.lang.Exception - If a SQLException occurs.

parseNotification

protected Notification parseNotification(java.lang.String source,
                                         java.lang.String type,
                                         java.lang.String code,
                                         java.sql.Date update,
                                         java.sql.Date expires,
                                         java.lang.String tracker,
                                         java.lang.String download)
                                  throws java.lang.Exception

Creates and returns a Notification based on the provided data. If the download string references a valid URL, then a URLNotification is created, otherwise a DefaultNotification is created.

Parameters:

source - The product source string.

type - The product type string.

code - The product code string.

update - The latest update date/time for the product.

expires - The date/time when this notification expires.

tracker - A reference to a URL where information about this product is posted.

download - A reference to a URL where one can download this product, or null if this is not a URLNotification.

Returns:

The generated notification, or null if one could not be created (but an exception did not occur).

Throws:

java.lang.Exception - If the tracker string cannot be successfully parsed into a valid URL.

getCorrectStatement

protected java.sql.PreparedStatement getCorrectStatement(java.util.List<java.lang.String> sources,
                                                         java.util.List<java.lang.String> types,
                                                         java.util.List<java.lang.String> codes)
                                                  throws java.lang.Exception

Parameters:

sources - List string of sources

types - List string of types

codes - List string of codes

Returns:

prepared query based on what is/is not null

Throws:

java.lang.Exception - if error occurs