Exam App Quick Start

Added by Igal Levy, last edited by Igal Levy on Dec 18, 2009  (view change)

Overview   |   Quick Start   |   Tech and Architecture   |   Functions   |   SDLC   |   Test   |   Deploy

Examinator Quick Start

Introduction

This document shows you how to quickly install, configure, and run Examinator, a multi-instance test-taking web application with a database store. You can run Examinator instances in both an unclustered mode (without Terracotta) and a clustered mode (with Terracotta). Tests demonstrating that in-memory data clustered with Terracotta remains coherent are also provided below.

For an Examinator quick start using Apache Maven, see Examinator Maven Project. For instructions on how to download and work with the source code in Eclipse, see Examinator Source Code.

Initial Setup

The following sections show how to set up Examinator, its database, and email properties required for registering new users.

Platform Summary

You must have JDK 1.5.x or greater installed. Run java -version in a terminal window to confirm the JDK version.

Be sure to install the JDK before proceeding.

Download the Examinator Package

Download the Examinator package.

Unpack the Examinator package in the desired parent directory. The name of the Examinator home directory, which is created under the chosen parent directory, has the format:

examinator-<version>

Create the Database

  1. Start the H2 database server from the Examinator home directory:
    UNIX/Linux
    bin/h2db.sh start
    Microsoft Windows
    bin\h2db.bat start
    You can stop the database with h2db.sh stop.
  2. Create the database schema:
    UNIX/Linux
    bin/h2db.sh create-exam-db
    Microsoft Windows
    bin\h2db.bat create-exam-db
  3. Confirm that the database is set up:
    UNIX/Linux
    bin/h2db.sh console
    Microsoft Windows
    bin\h2db.bat console
    1. A console login similar to the following should appear in your browser:
    2. Enter the value jdbc:h2:tcp://localhost/target/data/exam in the JDBC URL field.
      All other fields can remain unchanged.
    3. Click Connect.
      You should see the exam database schema listed in the left-hand panel of the console.

Default Data

The first time Examinator starts up, its bootstrap functionality adds default users to the database. During subsequent startups, the application adds the default data only if it isn't present. The default data consists of the following administrator and user accounts (username - password):

admin1 - passwd1
admin2 - passwd2 	
admin3 - passwd3 	
admin4 - passwd4 	
admin5 - passwd5 	
student1 - passwd1
student2 - passwd2
student3 - passwd3
student4 - passwd4
student5 - passwd5

If this is the initial installation of Examinator, this default data has not yet been added.

Configure Examinator to Use an SMTP Server

The exam application requires access to an SMTP mail server to send confirmation emails for new accounts. You configure an SMTP server in the mail.properties file located in <Examinator home directory>/webapps/examinator/WEB-INF/classes.

If you use only the default accounts shown in Default Data, an SMTP mail server is not required because no confirmation emails need to be sent.

You must edit the following properties:

  • examinator.from.email – An email address that represents the sender.
  • smtp.host - The address of any available SMTP server.

The remaining properties in mail.properties set the text that appears in the subject of different types of emails. A configured mail.properties file should appear similar to the following:

examinator.from.email=MyAddress@MyCompany.com
smtp.host=mail.MyCompany.com
subject.signup.confirmation=Welcome to Examinator
subject.password.reset.confirmation=Password reset confirmation
subject.password.reset.done=Your password has been reset

Download, Install, and Configure Terracotta

See the README file in the Examinator home directory for the version of Terracotta required for the version of Examinator you have. Then follow these steps:

  1. Download Terracotta.
    Installation is as simple as unpacking the package (UNIX/Linux) or running an installer (Microsoft Windows).
  2. Set the following environment variable: 
    TC_INSTALL_DIR=<path to Terracotta installation directory>
  3. From the Terracotta home directory, install all required TIMs:
    UNIX/Linux
    bin/tim-get.sh install-for <Examinator home directory>/tc-config.xml
    Microsoft Windows
    bin\tim-get.bat install-for <Examinator home directory>\tc-config.xml

Running the Exam Application Without Terracotta

You can use the embedded Jetty servers to run Examinator without Terracotta:

  1. Ensure that no other servlet container is running on ports 8080/8081.
    Connecting to http://localhost:8080 and http://localhost:8081 should fail.
  2. Start the database if it isn't running.
  3. Change to the Examinator home directory and start the first node:
    UNIX/Linux
    bin/startNode.sh 8080
    Microsoft Windows
    bin\startNode.bat 8080
  4. Repeat the previous step, changing the port number to 8081.
    Check console.log under work/8080/logs and work/8081/logs to make sure both Jetty instances finish starting up. Jetty is running when you see this type of message: 
    INFO: Started SelectChannelConnector@0.0.0.0:8080

    Two instances of Examinator should now be running, served by two Jetty instances and backed by a database.

Verifying that the Application is Not Clustered

With two instances of Examinator running, it is possible to test how data is handled and presented in an environment lacking Terracotta clustering. The test should demonstrate that while committed data is shared, in-memory data remains completely independent even in a case where it should be coherent. That is, data that has been committed to the database appears the same no matter which session accesses it, while data that is only in memory on the two nodes can quickly lose integrity as the application state diverges. In the second case, each session sees different data.

Create a User Account

This demonstration requires Examinator to have access to an SMTP mail server.

  1. Connect to http://localhost:8080/examinator and click the Register link.
  2. Fill in the form and submit it.
    A confirmation email is sent to the address you provided containing an URL similar to http://localhost:8080/examinator/registration/confirm.do and a confirmation code. Do not click the URL.
  3. Copy the indicated URL from the confirmation email to your browser's Location field and edit it so the port reads 8081 (in place of 8080) and the context path "examinator2" (in place of "examinator").
    The URL should now look like http://localhost:8081/examinator2/registration/confirm.do.
  1. Go to the confirmation page using the changed URL.
  2. In the confirmation email, copy the confirmation code.
    You need the confirmation code to complete the registration process.
  3. Complete the registration on the confirmation page by filling in the form, then click Finalize.
    The registration attempt is rejected due to invalid data.
  4. Using a different browser or browser tab, connect to the original URL:
    http://localhost:8080/examinator/registration/confirm.do
  5. Complete the registration on the confirmation page by filling in the form, then click Finalize.
    The registration is accepted.
    Since the application is not clustered, you can not switch between application servers without losing the session. The second instance of the application does not know about the pending registration held by the first instance. This is because unconfirmed registration data does not get committed, remaining in memory to help maximize performance.
Take a Test
  1. Log in to the new user account using http://localhost:8080/examinator.
    See Create a User Account. If you did not create a user account, use one of the default accounts.
  2. Click Take an Exam.
  3. Choose an exam and, following the on-screen directions, begin to answer questions.
  4. Log into the same user account using http://localhost:8081/examinator2.
  5. Click Take an Exam and attempt to take the same exam.
    To maximize performance, incomplete exams remain in memory. But since the application is not clustered with Terracotta, a second exam is started from the beginning, completely independent of the first exam already being taken. This happens even though:
    • Both sessions are using the same user account;
    • the user is taking the same exam;
    • the same database data is being accessed (see, for example, the exams offered and exam results).
      Note that questions which were answered during the first session appear again in the second, unanswered. Also, the time remaining to finish the second exam begins with the total time allowed, even though the first exam's allowed time has been run down since that exam started. The second instance of the application does not know about the exam being taken by the user in the first instance.

Running the Exam Application with Terracotta

Before continuing, take down the Jetty instances from the previous demonstration. Change to the Examinator home directory and stop the first node:

UNIX/Linux
bin/stopNode.sh 8080
Microsoft Windows
bin\stopNode.bat 8080

Stop the second node using the same command but changing the port number to 8081.

  1. Change to the Terracotta installation directory and start a Terracotta server instance:
    UNIX/Linux
    bin/start-tc-server.sh &
    Microsoft Windows
    bin\start-tc-server.bat
  2. Change to the Examinator home directory and start the Jetty application servers:
    UNIX/Linux
    bin/startCluster.sh &
    Microsoft Windows
    bin\startCluster.bat

    Check console.log under work/8080/logs and work/8081/logs to make sure both Jetty instances finish starting up. Jetty is running when you see this type of message:

    INFO: Started SelectChannelConnector@0.0.0.0:8080

The cluster should now be running with two instances of Examinator at the following addresses:

Several user accounts are created in the database by default. Usernames and passwords are listed above.

Verifying that the Application is Clustered

There are a number of ways to see how Terracotta introduces clustering to the exam application. Some examples are given below.

Create a User Account

This demonstration requires Examinator to have access to an SMTP mail server.

  1. Connect to http://localhost:8080/examinator and click the Register link.
  2. Fill in the form and submit it.
    A confirmation email is sent to the address you provided containing an URL similar to http://localhost:8080/examinator/registration/confirm.do and a confirmation code. Do not click the URL.
  3. Copy the indicated URL from the confirmation email to your browser's Location field and change the port to 8081.
    The URL should now look like http://localhost:8081/examinator/registration/confirm.do.
  4. Go to the confirmation page using the changed URL.
  5. In the confirmation email, copy the confirmation code.
    You need the confirmation code to complete the registration process.
  6. Complete the registration on the confirmation page by filling in the form, then click Finalize.
  7. Using a different browser or browser tab, connect to http://localhost:8080/examinator and log into the new account.
    Since the application is being clustered with Terracotta, you can switch between application servers without losing the session. The second instance of the application knows about the pending registration held by the first instance despite the fact that the data is in memory only.
Take a Test
  1. Log in to the new user account using http://localhost:8080/examinator.
    See Create a User Account.
  2. Click Take an Exam.
  3. Choose an exam and, following the on-screen directions, begin to answer questions.
  4. Log into the same user account using http://localhost:8081/examinator.
  5. Click Take an Exam and attempt to take the same exam.
    Since the application is being clustered with Terracotta, a second attempt to take the exam shows an exam in progress. Note that questions which were answered during the first connection appear answered, and that the time remaining to finish the exam is the same in both instances. The second instance of the application knows about the user's exam-in-progress on the first instance despite the fact that the data is in memory only.
Technology Stack and Architecture »

Labels

 
(None)