org.alltimeflashdreamer.mailwebform
Class MailWebFormServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended byorg.alltimeflashdreamer.mailwebform.AbstractMailWebFormServlet
              extended byorg.alltimeflashdreamer.mailwebform.MailWebFormServlet
All Implemented Interfaces:
MailWebFormConstants, Serializable, Servlet, ServletConfig

public class MailWebFormServlet
extends AbstractMailWebFormServlet

Title: MailWebFormServlet
Description: This class represents the core of the MailWebForm application part. It collects the required information to send a mail using the wrapper class org.alltimeflashdreamer.util.email.MailSender.
This information consists of the required and the optional parameters that are provided by either the server administrator (lowest in hierarchy) or the MailWebForm provider (using an overriding provider file) or the calling web site (highest priority; using URL parameters from e.g. hidden form inputs). In case the information is set in more than one of these sources, the source with the highest ranking is used.
The required parameters are the host name and the port number of the SMTP server to send the mails to as well as the sender's and the recipient's address (the recipient's name is recognized by the servlet too, but not required by specification).
Each additional URL parameter is treated as an optional parameter. They may be added to the MailWebForm calling web site, usually an input mask to send a mail to the provider of a web site (or someone else, but always to the same address). In case such additional/optional key-value pairs are found in the request object, they are added at the beginning of the message text, unless a mail template is defined. If one is defined, the placeholders in this template are replaced with the values of the URL parameters having the same name as those placeholders.
Example : Let's say one likes to have a gender checkbox on his input mask, and because he uses two different input masks to send mails with, he wants to configure indipendent send mail configurations. The solution for the first problem is to add a HTML input tag of type checkbox, named e.g. "isMale", and a text telling the user that he shall activate the checkbox in case he is man. The recipient will see a line "isMale = on" at the beginning of the mail, and no additional line in case the box remained unchecked. The second solution is to configure two different provider configurations in the admin tool and specify the send configuration using a hidden HTML input tag named "provider" in both sites. The value of the first one would perhaps be "myfirstsite" and the second one therefore "mysecondsite". This requires two files in the providers overwriting files or in the application's config directory, one named myfirstsite.properties and the second mysecondsite.properties, each of them having individually configured overwrite parameters.
For a HTML example, see the mailwebform_testexample.html file which is part of the distribution. The important tags (required and optional) are demonstrated and commented there.
The output which is produced after the sending of a site isn't designed at all. Therefore, one probably wants to replace this output with his own site. The provider of the mail sending site may show a site telling the user that the mail has been sent successfully (in case it was successful) or one telling him that the mail couldn't be delivered (in case of some error). However, he doesn't have to do this. In case these sites aren't defined for the current provider, the application looks for default settings (defined for the "system" provider in the Admin Tool). If those lack too, the servlet produces its own, ugly output.
The system settings allow the definition of a site which is shown in case the application's action method was called with illegal URL parameters, because some hacker was active or some robot tried to enter or even spam the site.
The decision which provider's settings are to be used to send a mail depends on the value of the URL parameter "provider". If this value isn't defined, either the spam error site (if defined) or an error message is shown by the servlet. If it's known, the settings for this provider are read from the different sources, and for each setting, the highest existing (in ranking, see above) is taken. Finally, the URL parameters named "subject" and "text" are received and their values added to the generated mail which is then sent to the provider's own or the application's default SMTP server.
If this servlet is accessed without URL parameters, a simple default input mask is shown, as a demonstration on the one and as a "is running" test on the other hand.

Version:
0.9
Author:
Copyright (c) 2001-2004 Florian Steinsiepe, Adrian Zaugg
See Also:
Serialized Form

Field Summary
(package private)  GlobalProperties globalProperties
          Properties instance storing the values read from the global properties file
(package private)  MailFormProviderList mailFormProviders
          the list of known providers of a mailwebform hosted by this servlet, including the "system" provider
 
Fields inherited from interface org.alltimeflashdreamer.mailwebform.MailWebFormConstants
ADMIN, ADMINSERVLET, APPNAME, COOKIENAME, CURRENTUSER, ERROR_URL, FILESEPARATOR, JSPBEAN, MAILFORMPROVIDER, MAILFORMPROVIDERLIST, MAILWEBFORM, MAILWEBFORMSERVLET, NEWLINE, PARAM_ADD, PARAM_APPLYGLOBAL, PARAM_APPLYINDIVIDUAL, PARAM_CANCEL, PARAM_CHANGE_CREDENTIALS, PARAM_CONFIGFILE, PARAM_CREDENTIALS_ADMIN, PARAM_EDIT, PARAM_ERRORURL, PARAM_FROMEMAIL, PARAM_FROMNAME, PARAM_LOGIN, PARAM_LOGOUT, PARAM_OVERWRITE, PARAM_PASSWORD, PARAM_PASSWORD_PROVIDER, PARAM_PROVIDER, PARAM_PROVIDERDIRECTORY, PARAM_REMOVE, PARAM_SMTPHOST, PARAM_SMTPPORT, PARAM_SPAMURL, PARAM_STORE, PARAM_SUBJECT, PARAM_SUCCESSURL, PARAM_TEMPLATE, PARAM_TEXT, PARAM_TOADDRESS, PARAM_TONAME, PARAM_USERNAME, PASSWORD, PASSWORDFILE, PLACEHOLDER_END, PLACEHOLDER_START, PROPERTY_CONFIGDIR, PROPERTY_SUFFIX, PROVIDERDIRECTORY, RESOURCENAME, SITE_CHANGE_CREDENTIALS, SITE_DEFAULTFORM, SITE_EDIT, SITE_ERROR, SITE_FOOTER, SITE_HEADER, SITE_LOGIN, SITE_MAIN, SITE_PROVIDER, SMTP_ALLOWOVERWRITE, SMTP_HOST, SMTP_PORT, SPAMERROR_URL, SUCCESS_URL, SYSTEMPROVIDER, TEMPLATE, TEMPLATE_SUFFIX, TOADDRESS, TONAME, USERNAME
 
Constructor Summary
MailWebFormServlet()
           
 
Method Summary
 void destroy()
          Cleans up pointers and closes resources.
 void doGet(HttpServletRequest request, HttpServletResponse response)
          Since this servlet makes no distinction between a GET and a POST, pass the GET requests over to the doPost method.
 void doPost(HttpServletRequest request, HttpServletResponse response)
          Looks for the URL parameters.
(package private) static String getConfigDirProperty()
          Reads the system property defining the app's config directory.
(package private)  File getCredentialsFile()
          Returns the abstract File instance pointing to the user credentials file.
(package private)  String getParameterIgnoreCase(HttpServletRequest request, String sKey)
          Searches the list of parameter names case-insensitively for the given key and returns the first value, if found.
(package private)  String[] getParameterValuesIgnoreCase(HttpServletRequest request, String sKey)
          Searches the list of parameter names case-insensitively for the given key and returns the value list, if found.
(package private)  File getPropertyFile()
          Returns the abstract File instance pointing to the global properties file.
(package private)  void printOutput(String sText, HttpServletResponse response)
          Prints the given text to the response's output writer, flushes and finally closes it.
(package private)  void readGlobalProperties()
          Reads the settings from the global properties file which must reside in the application classes' root folder.
(package private)  void showErrorScreen(MailWebFormException mwfe, HttpServletRequest request, HttpServletResponse response)
          Wraps the given error message into the JSPBean and redirects the client to the error page.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

globalProperties

GlobalProperties globalProperties
Properties instance storing the values read from the global properties file


mailFormProviders

MailFormProviderList mailFormProviders
the list of known providers of a mailwebform hosted by this servlet, including the "system" provider

Constructor Detail

MailWebFormServlet

public MailWebFormServlet()
Method Detail

doPost

public void doPost(HttpServletRequest request,
                   HttpServletResponse response)
            throws ServletException,
                   IOException
Looks for the URL parameters. If they're missing, the servlet is accessed for the first time, and the default form is shown, where the user can enter the e-mail information. Otherwise, we have the email info incoming, so we need to process it according to the caller's settings (if any, else use the default settings again).
Remember: The property files (both the global and the providers' ones) are always up to date. Just touch them on the file system (i.e. change it's modification date), and they will be reloaded the next time the servlet is accessed.

Specified by:
doPost in class AbstractMailWebFormServlet
Parameters:
request - contains the request parameters we need to have
response - contains the client's url to write to
Throws:
ServletException - in case problems occurred within the servlet container
IOException - in case problems occurred accessing a properties file

doGet

public void doGet(HttpServletRequest request,
                  HttpServletResponse response)
           throws ServletException,
                  IOException
Since this servlet makes no distinction between a GET and a POST, pass the GET requests over to the doPost method.

Parameters:
request - (see description of implementing doPost method)
response - (see description of implementing doPost method)
Throws:
ServletException - (see description of implementing doPost method)
IOException - (see description of implementing doPost method)

readGlobalProperties

void readGlobalProperties()
                    throws MailWebFormException
Reads the settings from the global properties file which must reside in the application classes' root folder. In case this file isn't found, the upcoming exception is wrapped into a ServletException which is thrown, for convenience with each possible caller method.

Throws:
MailWebFormException - wrapped and commented IOException, if one was thrown

getPropertyFile

File getPropertyFile()
               throws MailWebFormException
Returns the abstract File instance pointing to the global properties file. If the file doesn't exist or the servlet runner user can't write to it, an exception is thrown.

Returns:
the global property file wrapper
Throws:
MailWebFormException - if the file is missing or not editable

getCredentialsFile

File getCredentialsFile()
                  throws MailWebFormException
Returns the abstract File instance pointing to the user credentials file.

Returns:
the user credentials file wrapper
Throws:
MailWebFormException - if the system's configdir property isn't set

getConfigDirProperty

static String getConfigDirProperty()
                            throws MailWebFormException
Reads the system property defining the app's config directory. If this property isn't set, an exception is thrown since the app can't work without this directory.

Returns:
the path to the config dir, containing forward slashes only and ending with such a forward slash
Throws:
MailWebFormException - if the property isn't defined

getParameterIgnoreCase

String getParameterIgnoreCase(HttpServletRequest request,
                              String sKey)
Searches the list of parameter names case-insensitively for the given key and returns the first value, if found.

Parameters:
request - what to query for the URL parameters
sKey - the key that shall case-insensitively be searched for
Returns:
the first parameter value, if found, else null

getParameterValuesIgnoreCase

String[] getParameterValuesIgnoreCase(HttpServletRequest request,
                                      String sKey)
Searches the list of parameter names case-insensitively for the given key and returns the value list, if found.

Parameters:
request - what to query for the URL parameters
sKey - the key that shall case-insensitively be searched for
Returns:
the list parameter values, if found, else null

printOutput

void printOutput(String sText,
                 HttpServletResponse response)
           throws IOException
Prints the given text to the response's output writer, flushes and finally closes it.

Parameters:
sText - a text that is wrapped into a very simple HTML page
response - contains the client's url to write to
Throws:
IOException - thrown by the PrintWriter class, if any

showErrorScreen

void showErrorScreen(MailWebFormException mwfe,
                     HttpServletRequest request,
                     HttpServletResponse response)
               throws IOException
Wraps the given error message into the JSPBean and redirects the client to the error page.

Parameters:
mwfe - the application-specific error object that is to be rendered
request - the client's request object
response - used for redirecting the client
Throws:
IOException - thrown by the PrintWriter class, if any

destroy

public void destroy()
Cleans up pointers and closes resources.

Specified by:
destroy in interface Servlet