-
Notifications
You must be signed in to change notification settings - Fork 0
Developer Guide
The intent of this document is to describe the process of downloading, installing, and running our application. We will also describe the structure and function of the code in an effort to aid developers who wish to explore and/or extend the function of this application.
Notify Hawai'i was built on the Play for Java Web Application Framework and deployed to Heroku. As such, we will assume that you have already installed the following:
This application also utilizes 3rd party APIs to implement several functions. These dependencies are kept in the /lib/ directory and are included in the archive file available in our repository. Current dependencies are listed below:
- Create a new local PostgreSQL database file.
- Open a new terminal window and run psql.
- Create a new database file named "notify-hawaii" by executing the following command:
CREATE DATABASE notify-hawaii; - It is important that the database file is named correctly. If it is not, the application will not run.
- Check that the database has been successfully built with the
\lcommand.
- Navigate to our repository on Github. Download and extract your preferred archive file.
- Once the database is created Open a new terminal window and
cdinto the new directory. - Although it is not necessary, it is a good idea to run the integration tests now to ensure you're beginning with the code in a valid state. Integration tests are executed from the terminal with the
activator testcommand. - Run the application with the
activator runcommand. - Open your browser and navigate to
http://localhost:9000/to see the running application. - Press
Ctrl+Din the terminal window to exit the application.
Note: The application is not currently configured to persist data to a backend database, therefore, all information entered into the system will be lost when the application is terminated.
Authentication and Authorization has been implemented using the play-example-login github project by Dr. Phillip Johnson. While it is an effective approach to securing the application, there are several shortcomings including:
- Credentials are sent via http, not https.
- Credentials are stored in the database as string values.
- Account validation with email confirmations are not supported.
- Unable to login with 3rd party credentials (i.e. Google, Facebook, Linked-in, etc).
Despite these issues, we feel that this approach provides the services we require although we may consider moving to a more robust method such as play-authenticate in the future.
Deploying the web application to Heroku is fairly simple. Here are the steps:
- In a terminal window
cdinto the applications root directory. Make sure that this application is located in the master branch of a local Git repository.
- Create a new Heroku application with the following command:
heroku create
- Deploy the application by executing:
git push heroku master
- After a few minutes, the application will be deployed to Heroku and the url will be printed to the console.
The Notify Hawai'i application code is divided into three main packages: controllers, models, and views.
The views package contains the code that generates the HTML for each page in the application. Since this is its only purpose and specific to the function you are building, we won't discuss it here.
As can be guessed by its name, the models package holds the application's Model data or, in other words, the internal representation of the data. Currently there are two main classes implemented in this package, User and NewsArticle, as well as their supporting in-memory database classes. We will describe each of the main classes here:
User Class: The user class is the internal representation of each user of the application. Each user instance is associated with a first name, last name, email address, cellphone number and service provider. Currently, users can only be added to the database of users on application start up as the new user registration function has not yet been implemented.
UserDB Class: An in-memory database to store registered users of the application. This class allows for the adding, removing and editing of user information.
NewsArticle: The NewsArticle class is the internal representation of a single news article/story. Each instance of this class is associated with the url, title, and summary of the article. This class provides methods for retrieving the article data formatted for delivery in HTML or simple text.
NewsServicesSubscription: A simple class to keep track of News Subscription data. Each user is associated with a single instance of this class.
NewsServiceSubscriptionDB: An in-memory database that associates users with their News Service subscriptions.
Controllers are classes which implement the actions that can be performed on the data model. There are currently two separate packages that fall into this category: Communication and NewsServices.
In the Communication package we've implemented the classes and methods used to send email and text messages to a user. To use this function, simply call the send method of either the Email or TextMessage class and pass it the users email address or cellphone number, the subject line, and the message content. The rest is taken care of through the use of Apache Commons Email and JavaMail API calls.
The NewsServices package contains the classes that implement the functions specific to the scraping of news articles from newspaper websites. There are currently three sites from which we pull data; the Honolulu Star Advertiser, the Maui News, and Civil Beat; and each is associated with its own class. The reason for this is because the method of scraping data varies from one site to the next and must be built to accommodate the specific structure of each page.
This package also contains a NewsServices class. This class provides a single execute method that accepts a user object and that users subscriptions as parameters. It then generates and sends HTML and simple text messages based on that users subscriptions.
Each user is associated with a list of News Service subscriptions. Each subscription corresponds to the retrieval of specific types of articles from a set of newspaper websites. Classes in the NewsServices package implement the retrieval of news articles from these sites by using the Jaunt Webscraping Automation Tool. As pages are scraped, we identify the url, title, and summary of each article and create a corresponding NewsArticle object. These objects are used to generate the content of notifications. Sending of notifications are managed by the classes in the Communication package.
Thank you for your interest in the Notify Hawai'i web application!
Source code can be accessed at our Github Page here.
A running instance of the application on Heroku can be found here.
And if you have any questions or comments, our contact information is here.