org.locomotive.loco
Class Loco

java.lang.Object
  |
  +--org.locomotive.loco.Loco

public class Loco
extends java.lang.Object

The org.locomotive.loco.Loco is the primary entry point for the Org.Locomotive. Application Server. The server is launched by invoking the java interpreter on this class, which contains the main (String args[]) method.

A series of srguments may be specified as command line options. These include:

Only config properties which already exist in the default config tables can be added. If property is NAME="", then the value is entered as "", erasing any previous values.


Constructor Summary
Loco()
          a basic wrapper for the constructor
 
Method Summary
static boolean createDBConnectionPool(LocoConfig lc)
          creates the main Locomotive Database connection pool.
static void disposeDBConnection(java.sql.Connection c)
          throws away a Connection that has been corrupted, for example, by a SQLException, so that it will be deleted from the DBConnection Pool.
static java.lang.String evaluateTemplate(java.lang.String rel_path, java.util.Hashtable env)
          Evalute a template.
static int getActiveThreadCount()
          Returns the number of active RequestManager Threads.
static boolean getAutoSessionHandling()
          returns the current value of the auto_session_handling flag.
static LocoConfig getConfig()
          returns the LocoConfig of the server
static int getCurrentRequestID()
          gets the current value of the request id.
static java.sql.Connection getDBConnection()
          Gets a Connection from the Request Manager's DBConnection Pool.
static Log getEventLog()
          gets the reference to the main server log of the Loco
static DBCache getGlobalDBCache()
          Get the global DBCache for Loco.
static java.util.Properties getHandlerProperties(Handler h)
          This will return the Properties object associated with a Handler, if there is any.
static int getMaxThreadPoolSize()
          Returns the number of active RequestManager Threads.
static int getOpenDBConnectionCount()
          used by the Server Handler for status
static Log getServerLog()
          gets the reference to the main server log of the Loco
 java.lang.String getServerRoot()
          Get the server root.
static java.util.Date getStartupDate()
          returns the startup date of the Loco
static int getThreadPoolSize()
          Returns the number of active RequestManager Threads.
static java.lang.String getVersionString()
          returns the Version Number of the server
static void log(int lev, java.lang.String s)
          log to the Loco server log
static void logEvent(int level, HandlerData hd, java.lang.String major, java.lang.String minor, java.lang.String data)
          log to the Loco event log - simplified version
static void logEvent(int level, int rid, Session sess, User u, java.lang.String major, java.lang.String minor, java.lang.String data)
          log to the Loco event log
static void main(java.lang.String[] argv)
          This method is called by the JVM at server startup.
static void putBackDBConnection(java.sql.Connection c)
          Returns a Connection object back to the RequestManager DBConnection Pool.
static void redirect(java.lang.String request_uri, HandlerData hd)
          Redirects a given request to a new handler for completion.
protected static boolean reloadDBConnectionPool()
          Wipes all the current database connections from the DBConnectionPool and reloads it with new ones.
protected static void reloadHandler(java.lang.String handler)
          Marks the Handler class specified by the string for reloading, which means that upon the next request for that handler, the handler's properties file will be reloaded and the handler's init() method will be called.
protected static boolean reloadHandlerRoutingTable()
          Reloads the hrt.conf file, then reinitializes all the handlers and reloads each of their properties files.
static void reloadServlet(java.lang.String Servlet)
          Marks the Servlet class specified by the string for reloading, which means that upon the next request for that Servlet, the Servlet's properties file will be reloaded and the Servlet's init() method will be called.
static boolean reloadServletRoutingTable()
          Reloads the hrt.conf file, then reinitializes all the Servlets and reloads each of their properties files.
static void sendErrorMsg(java.lang.String error_msg, HandlerData hd)
          Displays and error page with Standard insertions, plus a the error string for the class.
static void setAutoSessionHandling(boolean on)
          toggle auto session handling
If true, which is the default, the RequestManager will automatically sense expired sessions.
static void setConnectionPool(DBConnectionPool connectionPool)
          Set the connection pool to use for this loco.
static void setEventLog(Log eventLog)
          set the event log for this loco.
static void setServerLog(Log serverLog)
          Set the log for this loco.
 void setServerRoot(java.lang.String serverRoot)
          Set the server root.
static void setStopAccepting()
          for shutting down the Loco.
static void setThreadPoolManager(ThreadPoolManager tpm)
          Set the thread pool manager for this loco.
static void startWebServers(java.lang.String server_list)
          Start up any/all web servers from the space-separated list of instance names passed to this method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Loco

public Loco()
a basic wrapper for the constructor
Method Detail

main

public static void main(java.lang.String[] argv)
This method is called by the JVM at server startup.

log

public static void log(int lev,
                       java.lang.String s)
log to the Loco server log
Parameters:
lev - the log level
s - a string to be logged

logEvent

public static void logEvent(int level,
                            HandlerData hd,
                            java.lang.String major,
                            java.lang.String minor,
                            java.lang.String data)
log to the Loco event log - simplified version
Parameters:
level - - the log level
hd - - a HandlerData object as passed into a handler
major - - the major event region or code section
minor - - the minor event code
data - - event specific data

logEvent

public static void logEvent(int level,
                            int rid,
                            Session sess,
                            User u,
                            java.lang.String major,
                            java.lang.String minor,
                            java.lang.String data)
log to the Loco event log
Parameters:
level - - the log level
rid - - the response id (used mostly for debugging)
sess - - the current session
u - - the User
major - - the major event region or code section
minor - - the minor event code
data - - event specific data

startWebServers

public static void startWebServers(java.lang.String server_list)
Start up any/all web servers from the space-separated list of instance names passed to this method. They each start in their own thread, load their own configuration files, etc.
Parameters:
server_list - a space-separated list of web server instance names to start. The instance names can be anything, but there must be an aptly-named config file for each.

evaluateTemplate

public static java.lang.String evaluateTemplate(java.lang.String rel_path,
                                                java.util.Hashtable env)
Evalute a template. Uses the default template root path as a base. The default template root is set via the primary Loco configuration file "loco.conf". If the default setup is not sufficient, it is possible for a handler implementor to use the CachedPageLoader directly.
Parameters:
rel_path - the relative path to the template file
env - the evaluation environment hash
See Also:
org.locomotive.server.CachedPageLoader

getServerLog

public static Log getServerLog()
gets the reference to the main server log of the Loco

setServerLog

public static void setServerLog(Log serverLog)
Set the log for this loco.

getEventLog

public static Log getEventLog()
gets the reference to the main server log of the Loco

setEventLog

public static void setEventLog(Log eventLog)
set the event log for this loco.

redirect

public static void redirect(java.lang.String request_uri,
                            HandlerData hd)
Redirects a given request to a new handler for completion. This routine might be useful when the originally called handler (first handler) determines that a second handler should be called to complete a request.

The handler_uri is parsed to create a new hd.url_tokens, which is then used to determine how the new request will be handled. It should appear as if the first handler was never called, with a few exceptions:
Any changes to variables in hd made by the first handler will remain, and the value of 'hd.url' (called hd.handler_uri in versions beyond 3.6) is left unmodified by the redirect. In future versions, it too may be reset to the value passed in via the redirect call.

If it is important for the second handler to know something about the first, we recommend passing a flag or data via the cgi_envars or subs hashes in hd.

Parameters:
handler_uri - the hander_uri specifying any parameters and the handler name to redirect to. A null or empty string will result in the DefaultHandler. Typically of the forms:

"/handler/pathtoken/other?querytoken1+querytoken2" or

"handler?querytoken1+querytoken2" or

"handler"

with zero or more path tokens and or zero or more query tokens, depending on how the url structure has been designed.

hd - the HandlerData instance passed into the first Handler, or a newly constructed one if necessary.

getActiveThreadCount

public static int getActiveThreadCount()
Returns the number of active RequestManager Threads. Allows you to get and idea of current load/concurrency.

getThreadPoolSize

public static int getThreadPoolSize()
Returns the number of active RequestManager Threads. Allows you to get and idea of current load/concurrency.

getMaxThreadPoolSize

public static int getMaxThreadPoolSize()
Returns the number of active RequestManager Threads. Allows you to get and idea of current load/concurrency.

setThreadPoolManager

public static void setThreadPoolManager(ThreadPoolManager tpm)
Set the thread pool manager for this loco.

getStartupDate

public static java.util.Date getStartupDate()
returns the startup date of the Loco

getCurrentRequestID

public static int getCurrentRequestID()
gets the current value of the request id. The value is incremented just before pulling a new client off the queue.

getDBConnection

public static java.sql.Connection getDBConnection()
Gets a Connection from the Request Manager's DBConnection Pool. This method might be called by various modules. The connection should be returned after use using putBackDBConnection().
Returns:
a connection from the Locomotive's internal database connection pool, or null if the connection pool has not been created yet.

putBackDBConnection

public static void putBackDBConnection(java.sql.Connection c)
Returns a Connection object back to the RequestManager DBConnection Pool. (used by Module cleanup threads) Putting back connections that were not fetched using getDBConnection() could damage the integrity of the DBConnectionPool and is not advised.

disposeDBConnection

public static void disposeDBConnection(java.sql.Connection c)
throws away a Connection that has been corrupted, for example, by a SQLException, so that it will be deleted from the DBConnection Pool.

getOpenDBConnectionCount

public static int getOpenDBConnectionCount()
used by the Server Handler for status

createDBConnectionPool

public static boolean createDBConnectionPool(LocoConfig lc)
creates the main Locomotive Database connection pool. if the DB_AUTOCONNECT is set to yes, then this occurs when the Locomotive is started. Otherwise it must be called by a handler.

reloadDBConnectionPool

protected static boolean reloadDBConnectionPool()
Wipes all the current database connections from the DBConnectionPool and reloads it with new ones. It uses the JDBC driver class, connection URL, username, and password specified in the loco.conf file. You may want to use this periodically if connections are getting locked thanks to bad code, drivers, or database bugs.

This isn't currently as safe as it should be, as it wipes the current connections without checking to see if it creates new ones. So, calling this could potentially result in a loco hang, if new connections can't be created. Watch out! Note, however, that this isn't as serious as it seems, because inability to create a new connection is often a symptom of problems that affect general database communication, and so the inability to reload would probably only happen when the loco isn't able to talk to the database at all.


setConnectionPool

public static void setConnectionPool(DBConnectionPool connectionPool)
Set the connection pool to use for this loco.
Parameters:
connectionPool - The connection pool.

setAutoSessionHandling

public static void setAutoSessionHandling(boolean on)
toggle auto session handling
If true, which is the default, the RequestManager will automatically sense expired sessions. The default timeout is 3600 seconds (one hour) and is configured via the primary Loco configuration file. Sessions that have not been active for greater than the timeout will be reset to a new session, stored in the database, and the a new browser session cookie will set in the current response object. If the previous session belonged to an authenticated user (aka, one who was logged in) they will be sent the default 'session expired' template, the request will then end and a handler will not be invoked. If the old session contained an anonymous user (or an " unauthenticated user") no message is sent, and the request is passed into the apprpriate handler with the new anonymous session. processing. If a handler needs to handle expired sessions on its own, setAutoSessionHandling should be passed "false". Note that this cannot be set on a per-handler basis.
Parameters:
on - new value of auto session handling flag

getAutoSessionHandling

public static boolean getAutoSessionHandling()
returns the current value of the auto_session_handling flag.
See Also:
setAutoSessionHandling

reloadHandler

protected static void reloadHandler(java.lang.String handler)
Marks the Handler class specified by the string for reloading, which means that upon the next request for that handler, the handler's properties file will be reloaded and the handler's init() method will be called.
If the string is left blank ("") or is null, then all Handler classes are reloaded- see markAllHandlersForReloading().
This only reinstantiates the class and re-reads the properties files. It doesn't go back and reload the hrt.conf file, nor does it actually reload the class into the VM.
Parameters:
token - the token that refers to the Handler class in the hrt.conf file

reloadHandlerRoutingTable

protected static boolean reloadHandlerRoutingTable()
Reloads the hrt.conf file, then reinitializes all the handlers and reloads each of their properties files. It doesn't actually reload Classes from their class files, though. The reload will occur on the next request to the Locomotive.
Returns:
true if we reloaded successfully, false if otherwise

getHandlerProperties

public static java.util.Properties getHandlerProperties(Handler h)
This will return the Properties object associated with a Handler, if there is any. The Properties object is created from a file specified in the hrt.conf file, and is loaded at startup and whenever the Handler is reloaded. If no Properties file was specified in the hrt.conf file, then this returns null.

Each Properties object associated with a Handler will have at least one variable in it-

   PROPERTIES_PATH 
which is the absolute path to the file the Properties were loaded from. This will allow Handlers to manipulate and re-store their Properties.
See Also:
Handler, HandlerData.handler_config

reloadServlet

public static void reloadServlet(java.lang.String Servlet)
Marks the Servlet class specified by the string for reloading, which means that upon the next request for that Servlet, the Servlet's properties file will be reloaded and the Servlet's init() method will be called.
If the string is left blank ("") or is null, then all Servlet classes are reloaded- see markAllServletsForReloading().
This only reinstantiates the class and re-reads the properties files. It doesn't go back and reload the hrt.conf file, nor does it actually reload the class into the VM.
Parameters:
token - the token that refers to the Servlet class in the hrt.conf file

reloadServletRoutingTable

public static boolean reloadServletRoutingTable()
Reloads the hrt.conf file, then reinitializes all the Servlets and reloads each of their properties files. It doesn't actually reload Classes from their class files, though. The reload will occur on the next request to the Locomotive.
Returns:
true if we reloaded successfully, false if otherwise

setStopAccepting

public static void setStopAccepting()
for shutting down the Loco. After handling the next inbound connection, the Loco will stop accepting new connections, do various cleanups, then exit

getConfig

public static LocoConfig getConfig()
returns the LocoConfig of the server

getGlobalDBCache

public static DBCache getGlobalDBCache()
Get the global DBCache for Loco.

getVersionString

public static java.lang.String getVersionString()
returns the Version Number of the server

sendErrorMsg

public static void sendErrorMsg(java.lang.String error_msg,
                                HandlerData hd)
Displays and error page with Standard insertions, plus a the error string for the class. The error string is set in the constructor. Evaluates the template LOCO_TEMPLATE_ROOT_PATH/error/generic_error.tmpl. LOCO_TEMPLATE_ROOT_PATH is the template directory, as specified in the Loco configuration file. If this template is missing, then it will send a generic html file including the message.
Parameters:
error_msg - The mesage to display. If left blank or null, then the following will message will be displayed:
Your request could not be processed due to an internal handler error.
hd - the handlerData object whose request we should send the response through.

getServerRoot

public java.lang.String getServerRoot()
Get the server root.
Returns:
Returns the server root.

setServerRoot

public void setServerRoot(java.lang.String serverRoot)
Set the server root.
Parameters:
serverRoot - The server root for this locomotive.