Overview
The Alerting Portlet aims to provide a JSR168 portlet and associated server-side infrastructure that allows users to receive messages alerting them to new resources available in areas that interest them. The source data areas are configured by the portal administrator, for example, an OAI e-journal repository. Portlet users create keyword-based subscriptions that run periodically and send notifications of new resources that match the keywords criteria.
The Alerting Portlet provides:
- A JSR168 portlet
- An administrator servlet
- A harvester component
- An alert delivery component
- Cron-like timer applications for both harvesting and alert delivery
Screenshots
This screenshot shows the creation of a subscription in the portlet:
http:/wiki/spp/images/spp-alerting-portlet1.png
This screenshot shows the viewing of the list of subscriptions in the portlet:
http:/wiki/spp/images/spp-alerting-portlet2.png
Getting Started
Use the Quick Start package to try out the application. Visit the ["Download"] page to fetch the latest version.
After unzipping the archive follow the instructions contained in the README.txt file.
For fuller configuration options see [#configuration] below.
Requirements
- Java 5 runtime or above - not included
- JMS message broker - Apache ActiveMQ included in quick start. It is possible to replace ActiveMQ with another broker if required.
- SQL Database - HSQL included in quick start. It is possible to configure the services to use another database if required.
- Portlet container - not included. Tested with Apache Pluto 1.0.1
- Servlet container - not included. Tested with Apache Tomcat 5.5
Architecture and Components
This diagram gives an overview of the static application architecture:
http:/wiki/spp/images/alerting_architecture_basic_v1.png
Clients
- The JSR168 portlet provides the end-user with a tool to manage their subscriptions. These user subscriptions are stored in the relational database.
- The administrative servlet provides an interface to configure the repositories that are to be harvested and made available to the portlet users. The repository details are also stored in the database.
Services
The back-end components co-ordinate their work via the use of a JMS message broker. Note that this means the components do not have to live on the same hardware, although in the quick start distribution this is the default for convenience. The components comprise:
- Harvester Job. A scheduled job that periodically checks to see if data source repositories are due an harvest. By default, it will run at 35 minutes past the hour.
- Harvester and Query Service. These services harvest data from remote repositories, index it, and respond to queries about that data.
- Alerting Job. A scheduled job that periodically checks to see if subscribers are due an alert for their subscriptions. By default, it will run at 30 minutes past the hour.
- Data Synchronization Daemon. A daemon that ensures that certain data about data sources is synchronized between the relational database and the RDF store.
- Alerting Delivery. A scheduled job that emails alerts to subscribers. By default it runs once a minute.
This diagram gives an example of the flow using the JMS broker, here as relates to the co-ordination of the Harvester Job, the Harvester and the Data Synchronization Daemon.
http:/wiki/spp/images/alerting_message_queue_v1.png
Configuration
Services
Alerting Delivery
The Alerting Delivery component should be viewed in conjunction with the other components of the portlet infrastructure and handles the delivery of the alerts that they generate.
In the Quick Start it can be found in spp-services/spp-alerting-delivery.
The default (and only, so far) implementation relies on JMS, and so requires a JMS Message Broker, e.g. Apache's ActiveMQ.
See etc/spp-alerting-delivery.properties for configurable options:
delivery.schedule.cronexpression. Delivery schedule. This is a cron expression that defines the frequency with which the delivery daemon should run.
delivery.mail.smtp.host. SMTP host to use for delivery.
delivery.mail.smtp.port. SMTP port.
delivery.mail.fromaddress. Address to use in the From: for outgoing alert emails.
delivery.alerts.maximum. Maximum number of alerts to include in one message. If the number of alerts exceeds this value the user will be notified that they are viewing a truncated set.
delivery.site.url. Site home page address. This will be included as $siteLink in the default email template.
delivery.body.velocitytemplatename. Name of Velocity template that provides the message body. Should live in etc/templates/.
Also review etc/jndi.properties. In particular the value of java.naming.provider.url needs to reflect your local setup.
Start and stop with:
> ant start-delivery-app > ant stop-delivery-app
Alerting Job
A scheduled job that periodically checks to see if subscribers are due an alert for their subscriptions.
In the Quick Start it can be found in spp-services/spp-alerting-job.
The implementation relies on JMS, and so requires a JMS Message Broker, e.g. Apache's ActiveMQ.
See etc/job.properties for configurable options:
job.frequency. Job schedule. This is a cron expression that defines the frequency with which the alert check should run.
broker.url. The URL of the JMS message broker.
There are also various JNDI-supplied message queue names defined in the properties files. It is recommended that these are left with the values supplied.
Also review etc/jndi.properties. In particular the value of java.naming.provider.url needs to reflect your local setup.
Also review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
Start and stop with:
> ant run > ant stop
Data Synchronization Daemon
A daemon that ensures that certain data about data sources is synchronized between the relational database and the harvester RDF store.
In the Quick Start it can be found in spp-services/spp-datasync-daemon.
The implementation relies on JMS, and so requires a JMS Message Broker, e.g. Apache's ActiveMQ.
See etc/daemon.properties for configurable options:
broker.url. This value should match your Message Broker installation. If you are using ActiveMQ on localhost then you do not need to change these values.
Also review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
Also review etc/jndi.properties. In particular the value of java.naming.provider.url needs to reflect your local setup. If you are using ActiveMQ on localhost then you do not need to change any values.
Start and stop with:
> ant run > ant stop
Harvester Job
A scheduled job that periodically checks to see if data source repositories are due an harvest.
In the Quick Start it can be found in spp-services/spp-harvester-job.
The implementation relies on JMS, and so requires a JMS Message Broker, e.g. Apache's ActiveMQ.
See etc/job.properties for configurable options:
job.frequency. Job schedule. This is a cron expression that defines the frequency with which the alert check should run.
broker.url. The URL of the JMS message broker.
There are also various JNDI-supplied message queue names defined in the properties files. It is recommended that these are left with the values supplied.
Also review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
Also review etc/jndi.properties. In particular the value of java.naming.provider.url needs to reflect your local setup. If you are using ActiveMQ on localhost then you do not need to change any values.
Start and stop with:
> ant run > ant stop
Harvester and Query Service
These services harvest data from remote repositories, index it, and respond to queries about that data.
In the Quick Start it can be found in spp-services/spp-harvester-job.
The default implementation relies on JMS, and so requires a JMS Message Broker, e.g. Apache's ActiveMQ.
For this recommended JMS configuration, check etc/harvester-MQ.properties for configurable options. In particular the database options should be reviewed in light of your environment. The default is to use file-based HSQL. This is not recommended for production environments.
Start with:
> ant start-harvester-MQ
Shutting down currently requires that you interact with the harvester by running the command line client in a separate terminal:
> ant start-client-MQ
Type 'help' for information on the available commands.
Clients
Alerting Portlet
The Alerting portlet provides the user interface for creating and managing alert subscriptions.
In the Quick Start it can be found in spp-clients/sppuserpref.war.
Once it has been installed into your portlet container, its configuration can be changed via files found in the WEB-INF directory.
Review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
The application should be accessed via your portal.
Admin Servlet
The Admin servlet provides an administrative interface to enable the management of repositories available to the user-facing portlet.
In the Quick Start it can be found in spp-clients/SppAdmin.war.
Once it has been installed into your servlet container, its configuration can be changed via files found in the WEB-INF directory.
Review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
The application should be accessed by visiting the index.html page with your browser.
Utilities
Database Creation
This utility creates the database required by the alerting portlet infrastructure.
In the Quick Start it can be found in spp-utils/spp-database-creation.
It should only be run once to initialize the database. Using it again will recreate the database and data such as subscriptions and datasources that might have been added to the system will be lost.
Review etc/database.properties to reflect your local database settings. Alter the different values to match the URL of the database, the class name of the JDBC driver and the username and password being used. Note: You will need to change the hibernate.dialect value if you are not using MySQL. The different dialect value are found in the Hibernate Manual.
Note that at present to run this requires use of the Quick Start package. In the Quick Start root directory:
> ant create-data
License
Copyright (c) 2007, University of Bristol All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3) Neither the name of the University of Bristol nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.