org.locomotive.loco.servlet
Class LocoServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--org.locomotive.loco.servlet.LocoServlet
Direct Known Subclasses:
BaseServlet, CodeGeneratorServlet, DiscussionAdminServlet, DiscussionServlet, DisplayPageServlet, GraffitiWallServlet, LoginServlet, LogoutServlet, PersonalPrefServlet, PublisherServlet, RegistrationServlet, UnknownServlet, UserMgtServlet, UserPrefServlet

public class LocoServlet
extends javax.servlet.http.HttpServlet
implements javax.servlet.SingleThreadModel

The LocoServlet class is a Servlet class you can use as a superclass for Servlets you're writing to use with the Locomotive. It provides most of the same functionality as the GenericHandler class. Notice that it implements SingleThreadModel, which means you can safely store stuff in instance variables of your subclasses, making it easier to pass information between methods during a request.

There are two alternative ways to use this class:

  1. You can subclass this class to handle all your user requests.
  2. You can create several different subclasses of this class in order to handle different features. Then, you can create a "master" subclass to route to each of these different subclasses, based on the different URLs.
This class comes with many convenience methods, some of which serve only to make the code more readable; feel free to customize them.

See Also:
GenericHandler, Serialized Form

Field Summary
protected  java.sql.Connection conn
          The database connection this request can use, if desired.
static int DEBUG
          log level to use for debugging
static int ERROR
          Log level to use for serious errors; e.g.
protected  FormData form_data
          the FormData object that contains any form information from a POST.
static int NORMAL
          log level to use for normal activities
protected  LocoServletRequest req
          The request object we received for this request
protected  javax.servlet.http.HttpServletResponse resp
          The response object to use for this request
protected  Session session
          the session associated with this request.
protected  java.util.Hashtable steam_vars
          the substitutions hashtable to be used when evaluating templates.
protected  java.lang.String[] url_tokens
          the url tokens for this request.
protected  User user
          the user associated with this request.
static int WARNING
          Log level to use for warnings
 
Constructor Summary
LocoServlet()
           
 
Method Summary
 java.lang.String displayPage(java.lang.String document_path, java.util.Hashtable steam_vars)
          loads a Steam document, inserts the values of Steam variables into that document, and then writes the result back to the Web server.
 void displayString(java.lang.String message)
          if you want to send back a single string as the response to the user, you can use this method.
 void handleException(java.lang.Exception exception, java.lang.String short_code)
          this is a convenience method you can use when you catch serious Exceptions for which you want a stack trace and you need to send the user an error code, which can help you debug.
 void log(int log_level, java.lang.String log_message)
          writes a message to the locomotive's global server log.
 void logEvent(java.lang.String major, java.lang.String minor, java.lang.String data)
          write one event to the global locomotive event log.
 void sayBadURL()
          simply tells the user that they typed a bad URL, by sending the message: "I'm sorry, I don't understand that URL."
 void service(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          The service method is the main entry point for Servlets.
 void setup(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          This will set up the various fields the class requires.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doGet, doOptions, doPost, doPut, doTrace, getLastModified, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, init, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

req

protected LocoServletRequest req
The request object we received for this request

resp

protected javax.servlet.http.HttpServletResponse resp
The response object to use for this request

url_tokens

protected java.lang.String[] url_tokens
the url tokens for this request.

form_data

protected FormData form_data
the FormData object that contains any form information from a POST.

steam_vars

protected java.util.Hashtable steam_vars
the substitutions hashtable to be used when evaluating templates.

user

protected User user
the user associated with this request.

session

protected Session session
the session associated with this request.

conn

protected java.sql.Connection conn
The database connection this request can use, if desired.

ERROR

public static final int ERROR
Log level to use for serious errors; e.g. log(ERROR, "Wait! There's an error!");

WARNING

public static final int WARNING
Log level to use for warnings

NORMAL

public static final int NORMAL
log level to use for normal activities

DEBUG

public static final int DEBUG
log level to use for debugging
Constructor Detail

LocoServlet

public LocoServlet()
Method Detail

setup

public void setup(javax.servlet.http.HttpServletRequest req,
                  javax.servlet.http.HttpServletResponse resp)
           throws java.io.IOException,
                  javax.servlet.ServletException
This will set up the various fields the class requires. This sh ould be called at the very beginning of each request, and is called in this class's version of service(), so it should be set up for you as long as you don't override service, and only use goGet(), doPost(), etc., as your request handling methods.
See Also:
service(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

service

public void service(javax.servlet.http.HttpServletRequest req,
                    javax.servlet.http.HttpServletResponse resp)
             throws java.io.IOException,
                    javax.servlet.ServletException
The service method is the main entry point for Servlets. All this method does is call the setup() method to get everything ready for the request, and then call super.service() to send the request off to the appropriate do() method (i.e. doGet(), doPost(), etc).

If you choose to override this method in a sub class, don't forget to call the setup() method at the beginning of your version.

Overrides:
service in class javax.servlet.http.HttpServlet
See Also:
setup(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), javax.servlet.http.HttpServlet.html#service

log

public void log(int log_level,
                java.lang.String log_message)
writes a message to the locomotive's global server log.
Parameters:
log_level - 0 is most severe. The higher, the less severe. Messages with log_levels higher than the variable LOG_LEVEL (from the file loco.conf) will be suppressed from being written to the log.
log_message - the message to write to the log.

handleException

public void handleException(java.lang.Exception exception,
                            java.lang.String short_code)
this is a convenience method you can use when you catch serious Exceptions for which you want a stack trace and you need to send the user an error code, which can help you debug.
Parameters:
exception - the exception to print to the server log.
short_code - the error message to send to the user

logEvent

public void logEvent(java.lang.String major,
                     java.lang.String minor,
                     java.lang.String data)
write one event to the global locomotive event log. (this method is just a wrapper around Loco.logEvent().)

example:

logEvent (5, "login", "submit_form", user.getUsername());
Parameters:
major - the major event region or code section
minor - the minor event code
data - event specific data

displayString

public void displayString(java.lang.String message)
                   throws java.io.IOException
if you want to send back a single string as the response to the user, you can use this method. (You don't need to put your message within <HTML><BODY>...</BODY></HTML>)

displayPage

public java.lang.String displayPage(java.lang.String document_path,
                                    java.util.Hashtable steam_vars)
                             throws java.io.IOException
loads a Steam document, inserts the values of Steam variables into that document, and then writes the result back to the Web server.
Parameters:
document_path - -- the file path of that document, relative to the template root.
Returns:
a String containing the fully evaluated Steam document, after inserting all the variables. If the document with that file path does not exist, then returns "", an empty String. If another page has already been displayed, will return "".

sayBadURL

public void sayBadURL()
               throws java.io.IOException
simply tells the user that they typed a bad URL, by sending the message: "I'm sorry, I don't understand that URL."