Getting started with PA1

Implementation guidelines

Given the application that you have to develop, you need to first define the schema, i.e. the tables that you want to create in order to store the required data. In this assignment you will be using PostgreSQL. You do not need to implement the creation of tables in JDBC. You can use the psql command line client to create tables and test the SQL commands.

Then, for each of the required tasks in your application you should write a function (or more than one if you want) that uses at least one SQL statement and implements the required task.You can test the task using a Java program and JDBC. We strongly recommend that you have separate functions for each query/task as you will be using the same to implement a web frontend with JSP. Don't forget to put a semicolon(;) at the end of each SQL statement. Make sure to use VARCHAR instead of CHAR. Otherwise equality will be difficult to check in your Java code. We next give the steps to get started. We have an example that accesses the database via JDBC using a standalone Java application in Lab 6. We describe a similar database access example using JSP in Lab 8.

General setup

  1. All instructions given below are designed to only work on "csa1.bu.edu", "csa2.bu.edu" and "csa3.bu.edu". Using "csa3.bu.edu" is recommended. Make sure you are logged into one of these machines before you proceed.

  2. Create a directory for this project and cd to that directory. Hereafter, this directory (the full path of this directory) shall be referred to as $PA1DIR

  3. Execute: tar xvf /cs/coursedata/cs460/pa1.tar (if you get an error try /usr/bin/tar instead of tar). You can also download the file from here: pa1.tar, copy the file to the directory and run: tar xvf pa1.tar

Setting up postgres and JDBC

  1. You should have received an email with your postgres username and password.

  2. Shell configuration: If you use bash shell (this is the default for your cs account), add the following lines in the .bashrc file in your home directory.

    export ANT_HOME=$PA1DIR/apache-ant-1.6.5 # Make sure that you replace $PA1DIR with the actual directory!

    export JAVA_HOME=/usr

    export PATH=$ANT_HOME/bin:$PATH

    export PGPORT=5432

    export PGUSER=<postgres user name: this should be changed>

    export PGPASSWORD=<postgres password assigned to you: this should be changed>

  1. Close and reopen your terminal.

  2. Check your postgres account by running psql. Enter some SQL commands to ensure everything is ok. (You just need to run psql and you should get to the database with the same name as your account name.)

Setting up and running the skeleton application

For this project assignment we have a created a skeleton application which demonstrates:

  1. how to upload images from a JSP page

  2. how to store upload images to the database

  3. how to create image thumbnails

  4. how to retrieve and display stored images

Getting this application to run should be your first priority. Here is how to do it:

  1. Configure Tomcat

  2. Create the appropriate database tables

  3. Configure the application

  4. Compile the application

    Note: this step will have to be repeated whenever you make changes to your application.

  5. Deploy the application Now that the web application archive has been created you should copy it to the appropriate Tomcat directory using

    Note: this step will have to be repeated whenever you make changes to your application.

  6. Starting and testing tomcat:

If you got everything right you should be able to upload some JPEG (that's the only image format we will consider) images and see the created thumbnails once you authenticate yourself. The system comes with a preconfigured user test@bu.edu whose password is test. Use these credentials to log in. If something went wrong, verify that you followed all of the above steps properly and no error messages were produced in the process.

Authentication and authorization using Tomcat

To authenticate users and authorize access to protected pages on the website which you are going to build you will be using Tomcat's embedded security mechanisms. As the project is mainly concerned with the database interaction we have implemented this functionality for you in the skeleton application. Despite the fact the implementation is provided you will have to understand how it works so that you can tweak it appropriately to match your system's requirements. The first thing to check is that your photoshare/META-INF/context.xml file contains the following XML snippet 

<Realm className="org.apache.catalina.realm.JDBCRealm"
        driverName="org.postgresql.Driver"
        connectionURL="jdbc:postgresql://cs460.bu.edu:5432/YOUR_POSTGRES_USERNAME"
        connectionName="YOUR_POSTGRES_USERNAME" connectionPassword="YOUR_POSTGRES_PASSWORD"
        userTable="Users" userNameCol="email" userCredCol="password"
        userRoleTable="Users" roleNameCol="role_name" />

What the above configuration directive does is to tell Tomcat that protected resources should be authenticated and authorized against the Users table in your database. Here is the minimal contents of the Users table. 

CREATE TABLE Users
(
        user_id int4 NOT NULL DEFAULT nextval('Users_user_id_seq'),
        email varchar(255) NOT NULL,
        password varchar(255) NOT NULL,
        role_name varchar(255) NOT NULL DEFAULT 'RegisteredUser',
        CONSTRAINT users_pk PRIMARY KEY (user_id)
);

This is just and example and is not the exact same Users table in which your system's users will be stored, i.e., you will have to add extra columns to this table to match the requirements of the application as they have been documented elsewhere. Next, what you have to do is to restrict access to some pages in your Web application. Again, a minimal configuration is defined in the file photoshare/WEB-INF/web.xml which looks like the following: 

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>PhotoshareRealm</web-resource-name>
            <description>Pages accessible by registered users</description>

            <!-- PAGES ACCESIBLE ONLY BY REGISTERED USERS SHOULD BE ADDED HERE -->
            <url-pattern>/index.jsp</url-pattern>
            <url-pattern>/someOtherProtectedPage.jsp</url-pattern>
            <!--
            THIS IS AN EXAMPLE OF A PATTERN TO MATCH MANY PAGES
            <url-pattern>/protected/*.jsp</url-pattern>
            -->
            <!-- ============================================================= -->

            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>RegisteredUser</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>FORM</auth-method>
        <form-login-config>
            <form-login-page>/login.jsp</form-login-page>
            <form-error-page>/loginerror.jsp</form-error-page>
        </form-login-config>
    </login-config>

The comments above direct you as to where to add other pages that are protected - it should be pretty straightforward. The final lines simply tell Tomcat that users whose credentials we do not know yet should be directed to the page login.jsp and in case of a login error to loginerror.jsp. These pages are also provided for you. Once a user is authenticated they are redirected to their original destination. Another useful function an example of which is provided is getting the currently authenticated user from Tomcat. Inside index.jsp you will find the lines: 

Hello <b><code><%= request.getUserPrincipal().getName()  %></code></b>, click here to
<a href="/photoshare/logout.jsp">log out</a>

which indicates how to retrieve the username (in our case the email) of the visitor performing the current request. Knowing of and understanding the above functionality should be all you need in terms of authentication and authorization to complete this project.

Photos and thumbnails

Image storage and thumbnail creation is provided for you is the skeleton application. You should reuse this code. When a new image is uploaded to the database its thumbnail is also automatically created and stored (have a look at Picture.createThumbnail()). Both the original picture and its thumbnail can be retrieved using the ImageServlet which is also provided. To access a picture just point your browser at the following url http://csa3.bu.edu:yourport2/photoshare/img?picture_id=XXX Replacing XXX with the actual numeric picture id. Similarly, for a thumbnail the url is http://csa3.bu.edu:yourport2/photoshare/img?picture_id=XXX&t=1

Adding your own files

Now, that you have everything up and running it's time to start adding your own files. JSP pages should be placed under: 

+---resources

whereas Java source files under 

+---src

Remember, whenever you make changes to your application and you want to re-deploy it, you will need to rerun the two steps highlighted above. They are:

ant -f photoshare.xml all

cp photoshare/photoshare.war apache-tomcat-5.5.15/webapps


and if everything worked as expected and Tomcat picked up the new deployment you should see something like that

XX-Oct-2015 XX:XX:XX org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive photoshare.war

in the logfile catalina.2015-XX-XX.log

Good luck!