Class VocTrainer

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--VocTrainer
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class VocTrainer
extends javax.servlet.http.HttpServlet

VocTrainer is a servlet. It is designed to run with the vq-server on Windows  platforms. It may also run with other servers on different platforms as well, but this has not been tested, yet.

VocTrainer is a (as one can guess from the name) vobable trainer. For more detailed information on the performance and abilities of this software please read the (TeX, pdf) documentation that goes with this distribution. The following text describes the general concept and the implementation of this servlet.

The two commonly used methods in a servlet are the doPost(..) and doGet(..) methods. We combined these two methods to a simple doMain(..) methods for we do not really need to differ between post and get. The doMain method handles the user administration stuff that is needed for most servlets. If the servlet is called the first time by a user there is no event specified and no HTML page supplied. In this case the login HTML template is shown. The other actions that are provided by this method are deleting a user and generating a new account. All other events are delegated to the handleEvent(...) method of this class.

There is no direct access to the database that holds the information of the users. All database access is shielded by either the UserAdministration class (for user information) or VocableAdministration class (for vocable information). If you are interested in the database connection and handling please read the documentation of these two classes.

To be more flexible in displaying HTML pages we use HTML template files. A template file is a file which contains most of the information but also leaves some gaps to fill in case dependend data, such a a nickname or the secure identity of a user. The template files are handled using the HTMLTemplate class. To understand the following concepts you should be familiar with the HTMTemplate class and the basic methods of the UserAdministration.

The base concept is that there is a HTML form which at least has three fields:

  1. event: The event that should be handled. E.g. "login".
  2. id: The id of the user.
  3. secureidentity: A random String that is given to a user when she logs in. This key is unique during a session.

If there is no event specified then the login HTML template is shown by default. If there is a event specified that is not handled by the servlet an error HTML template is shown. In all other cases the code block for the eventhandling is responsible for the following pages displayed. Any uncaught Exception will also force to display the error page.

The steps in the eventhandling:

  1. clear all variables from the previous session.
  2. check if there is an event. If no event show login template
  3. retrieve id and secureidentity. Used to authorize a user. If a user is not logged in, these fields are empty.
  4. handle specified event. If either login, delete or  newuser.
  5. if there is an other event check the users id and secureidentity. This uses the UserAdministration.getUser(..) method. If the user can be authorized the event handling is delegated to the "inner side event handling" of the servlet: handleEvents(...).
  6. set the id and the secureidentity of the authorized user for the next template. It is important never to loose this information when displaying a HTML page. The user will loose her authorization!
  7. build up the next HTML template (depends on the specified event). Means fill the gaps in the template.
  8. send the HTML file back to the user.
  9. wait for the next request.

Dear subclassers:

It' s possible to subclass this servlet to take advantage of the already build login procedure. Please ensure when you plan to do so that you overwrite the handleEventMethod of this class. In this case do call the the method before you do your own eventhandling. A returnvalue null means that the event was not handled. Any other returnvalue should be taken as result and be returned! Please read the description of the method carefully. The second important thing is that you do use the same user fields in your database as they are used in the sample database distributed with this package. See the UserAdministration class for more detailed information of the database structure.

DO NOT USE THE FOLLOWING EVENTS:

See Also:
Serialized Form

Field Summary
protected  java.util.Locale locale
          the locale that is used to display the templates and messages.
protected  java.util.ResourceBundle rb
          the ResourceBundle for this servlet.
protected  ServletParameters servletParam
          holds the servlet parameters of the configuration, e.g.
protected  HTMLTemplate template
          holds the variables and HTML template files.
protected  SimpleUserAdministration userAdmin
          user administration
 
Constructor Summary
VocTrainer()
           
 
Method Summary
 void doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Delegates to doMain(...)
 void doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Delegates to doMain(...)
protected  java.lang.String handleEvents(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, User user, java.lang.String event)
          Handles all events of the actual servlet implementation except the user administration and login.
 void init(javax.servlet.ServletConfig in_conf)
          initializes this servlet
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

userAdmin

protected SimpleUserAdministration userAdmin
user administration

servletParam

protected ServletParameters servletParam
holds the servlet parameters of the configuration, e.g. the name of the servlet or the real path.

template

protected HTMLTemplate template
holds the variables and HTML template files.

locale

protected java.util.Locale locale
the locale that is used to display the templates and messages.

rb

protected java.util.ResourceBundle rb
the ResourceBundle for this servlet.
Constructor Detail

VocTrainer

public VocTrainer()
Method Detail

init

public void init(javax.servlet.ServletConfig in_conf)
          throws javax.servlet.ServletException
initializes this servlet
Overrides:
init in class javax.servlet.GenericServlet

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws javax.servlet.ServletException,
                  java.io.IOException
Delegates to doMain(...)
Overrides:
doGet in class javax.servlet.http.HttpServlet

doPost

public void doPost(javax.servlet.http.HttpServletRequest request,
                   javax.servlet.http.HttpServletResponse response)
            throws javax.servlet.ServletException,
                   java.io.IOException
Delegates to doMain(...)
Overrides:
doPost in class javax.servlet.http.HttpServlet

handleEvents

protected java.lang.String handleEvents(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response,
                                        User user,
                                        java.lang.String event)
                                 throws java.lang.Exception
Handles all events of the actual servlet implementation except the user administration and login. To add a additional event please insert a new
else if ( event.equals("YOUR EVENT") ) block where your event is handled. Please take care of other events already specified if you're adding events to an existing servlet. If you're writing a new servlet using this one as a back bone. please subclass and overwrite this method with your own events.
IMPORTANT: Do not call template.clear() or template.clearVariables() method from this method. If you do ensure to copy the secureidentity and id variables into the new variables hash! If you do not care about this, the user will loose her authorization!
Parameters:
request - The request from doMain().
response - The response from doMain().
user - The authorized user.
event - The event that should be handled.
Returns:
The already build template file as a String. This string is sent directly to the browser, without any further modifications. If the given event is not handled then this method should return null.