dods.servlet
Class DODSServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended bydods.servlet.DODSServlet
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
Direct Known Subclasses:
dodsSQLServlet, dts

public abstract class DODSServlet
extends javax.servlet.http.HttpServlet

DODSServlet is the base servlet class for all DODS servers. (Well, all DODS servers running as java servlets) Default handlers for all of the acceptable DODS client requests are here.

Each of the request handlers appears as an adjunct method to the doGet() method of the base servlet class.

This is an abstract class because it is left to the individual server development efforts to write the getDDS() and getServerVersion() methods. The getDDS() method is intended to be where the server specific DODS server data types are used via their associated class factory.

This code relies on the javax.servlet.ServletConfig interface (in particular the getInitParameter() method) to retrieve the name of a .ini file containing information about where to find extensive configuration information used by the servlet. Alternate methods for establishing this functionality can be arranged by overloading the method loadIniFile()

The servlet should be started in the servlet engine with the following initParameters set:

For the old jswdk servlet engine:

 dts.code=dods.servers.test.dts
 dts.initparams=iniFilePath=/usr/dods/dts,iniFileName=dts.ini
 
For the tomcat servlet engine:
    <servlet>
        <servlet-name>
            dts
        </servlet-name>
        <servlet-class>
            dods.servers.test.dts
        </servlet-class>
        <init-param>
            <param-name>iniFilePath</param-name>
            <param-value>/usr/dods/dts</param-value>
        </init-param>
        <init-param>
            <param-name>iniFileName</param-name>
            <param-value>dts.ini</param-value>
        </init-param>
    </servlet>
 

Assuming, of course, that the .ini file is located in /usr/dods/dts and is named dts.ini. For example .ini files look in the subdirectory Java-DODS/.ini (where Java-DODS is the top of the distribution).

Also, the method processDodsURL() could be overloaded if some kind of special processing of the incoming request is needed to ascertain the DODS URL information.

Author:
Nathan David Potter
See Also:
processDodsURL(HttpServletRequest), Serialized Form

Constructor Summary
DODSServlet()
           
 
Method Summary
 void anyExceptionHandler(java.lang.Throwable e, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Sends an error to the client.
 void badURL(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Sends an html document to the client explaining that they have used a poorly formed URL and then the help page...
 void dodsExceptionHandler(DODSException de, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Sends a DODS error to the client.
 void doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          *********************************************************************** Handles incoming requests from clients.
 void doGetASC(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for DODS ascii data requests.
 void doGetCatalog(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Default handler for DODS catalog.xml requests.
 void doGetDAS(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for the client's DAS request.
 void doGetDDS(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for the client's DDS request.
 void doGetDIR(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for the client's directory request.
 void doGetDODS(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for the client's data request.
 void doGetHELP(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Default handler for the client's help request.
 void doGetHTML(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for DODS .html requests.
 void doGetINFO(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ReqState rs)
          ************************************************************************ Default handler for DODS info requests.
 void doGetStatus(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Default handler for DODS status requests; not publically available, used only for debugging
 void doGetVER(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Default handler for the client's version request.
protected  DAS getDAS(ReqState rs)
          ************************************************************************

In this (default) implementation of the getDAS() method a locally cached DAS is retrieved and parsed.

protected abstract  GuardedDataset getDataset(ReqState rs)
          ************************************************************************ This method must be implemented locally for each DODS server.
 java.lang.String getServerName()
          ************************************************************************

In this (default) implementation of the getServerName() method we just get the name of the servlet and pass it back.

abstract  java.lang.String getServerVersion()
          ************************************************************************ This function must be implemented locally for each DODS server.
 void init()
          ************************************************************************ Intitializes the servlet.
protected  boolean isTheClientCompressed(javax.servlet.http.HttpServletRequest request)
          Deprecated. This method has been encapsulated in the ReqState object and is no longer needed here.
 java.io.DataInputStream openCachedDAS(ReqState rs)
          ************************************************************************ Opens a DAS cached on local disk.
 java.io.DataInputStream openCachedDDS(ReqState rs)
          ************************************************************************ Opens a DDS cached on local disk.
 void parseExceptionHandler(ParseException pe, javax.servlet.http.HttpServletResponse response)
          ************************************************************************ Turns a ParseException into a DODS error and sends it to the client.
protected  void printCatalog(java.io.PrintWriter os)
           
protected  void printStatus(java.io.PrintWriter os)
           
 void probeRequest(javax.servlet.http.HttpServletRequest request)
          ************************************************************************ This is a bit of instrumentation that I kept around to let me look at the state of the incoming HttpServletRequest from the client.
protected  ReqState processDodsURL(javax.servlet.http.HttpServletRequest request)
          Deprecated. This method has been moved to the ReqState object and is no longer needed here.
 void sendDODSError(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String clientMsg, java.lang.String serverMsg)
          ************************************************************************ Sends a DODS error (type UNKNOWN ERROR) to the client and displays a message on the server console.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DODSServlet

public DODSServlet()
Method Detail

getServerVersion

public abstract java.lang.String getServerVersion()
************************************************************************ This function must be implemented locally for each DODS server. It should return a String containing the DODS Server Version...


getDataset

protected abstract GuardedDataset getDataset(ReqState rs)
                                      throws DODSException,
                                             java.io.IOException,
                                             ParseException
************************************************************************ This method must be implemented locally for each DODS server. The local implementation of this method is the key piece for connecting any localized data types that are derived from the dods.dap.Server types back into the running servlet.

This method should do the following:

Parameters:
rs - The ReqState object for this client request.
Returns:
The ServerDDS object all parsed and ready to roll.
Throws:
DODSException
java.io.IOException
ParseException
See Also:
ServerDDS, sqlServerFactory, test_ServerFactory

init

public void init()
          throws javax.servlet.ServletException
************************************************************************ Intitializes the servlet. Init (at this time) basically sets up the object dods.util.Debug from the debuggery flags in the servlet InitParameters. The Debug object can be referenced (with impunity) from any of the dods code...

Throws:
javax.servlet.ServletException

parseExceptionHandler

public void parseExceptionHandler(ParseException pe,
                                  javax.servlet.http.HttpServletResponse response)
************************************************************************ Turns a ParseException into a DODS error and sends it to the client.

Parameters:
pe - The ParseException that caused the problem.
response - The HttpServletResponse for the client.

dodsExceptionHandler

public void dodsExceptionHandler(DODSException de,
                                 javax.servlet.http.HttpServletResponse response)
************************************************************************ Sends a DODS error to the client.

Parameters:
de - The DODS exception that caused the problem.
response - The HttpServletResponse for the client.

anyExceptionHandler

public void anyExceptionHandler(java.lang.Throwable e,
                                javax.servlet.http.HttpServletResponse response,
                                ReqState rs)
************************************************************************ Sends an error to the client.

Parameters:
e - The exception that caused the problem.
response - The HttpServletResponse for the client.

getDAS

protected DAS getDAS(ReqState rs)
              throws DODSException,
                     ParseException
************************************************************************

In this (default) implementation of the getDAS() method a locally cached DAS is retrieved and parsed. In this method the DAS for the passed dataset is loaded from the "das_cache_dir" indidcated in the "[Server]" section of the DODSiniFile. If the there is no file available a DODSException is thrown. It is certainly possible (and possibly very desirable) to override this method when overriding the getDDS() method. One reason for doing this is if the DODS server being implemented can generate the DAS information dynamically.

When overriding this method be sure that it does the following:

Parameters:
rs - The ReqState object for this client request.
Returns:
The DAS object for the data set specified in the parameter dataSet
Throws:
DODSException
ParseException
See Also:
DAS

sendDODSError

public void sendDODSError(javax.servlet.http.HttpServletRequest request,
                          javax.servlet.http.HttpServletResponse response,
                          java.lang.String clientMsg,
                          java.lang.String serverMsg)
                   throws java.io.IOException,
                          javax.servlet.ServletException
************************************************************************ Sends a DODS error (type UNKNOWN ERROR) to the client and displays a message on the server console.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
clientMsg - Error message String to send to the client.
serverMsg - Error message String to display on the server console.
Throws:
java.io.IOException
javax.servlet.ServletException

openCachedDDS

public java.io.DataInputStream openCachedDDS(ReqState rs)
                                      throws DODSException
************************************************************************ Opens a DDS cached on local disk. This can be used on DODS servers (such as the DODS SQL Server) that rely on locally cached DDS files as opposed to dynamically generated DDS's.

This method uses the iniFile object cached by loadIniFile() to determine where to look for the cached DDS.

Parameters:
rs - The ReqState object for this client request.
Returns:
An open DataInputStream from which the DDS can be read.
Throws:
DODSException

openCachedDAS

public java.io.DataInputStream openCachedDAS(ReqState rs)
                                      throws java.io.FileNotFoundException
************************************************************************ Opens a DAS cached on local disk. This can be used on DODS servers (such as the DODS SQL Server) that rely on locally cached DAS files as opposed to dynamically generated DAS's.

This method uses the iniFile object cached by loadIniFile() to determine where to look for the cached DDS.

If the DAS cannot be found an error is sent back to the client.

Parameters:
rs - The ReqState object for this client request.
Returns:
An open DataInputStream from which the DAS can be read.
Throws:
java.io.FileNotFoundException

doGetDAS

public void doGetDAS(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     ReqState rs)
              throws java.io.IOException,
                     javax.servlet.ServletException
************************************************************************ Default handler for the client's DAS request. Operates on the assumption that the DAS information is cached on a disk local to the server. If you don't like that, then you better override it in your server :)

Once the DAS has been parsed it is sent to the requesting client.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
rs - The ReqState object for this client request.
Throws:
java.io.IOException
javax.servlet.ServletException

doGetDDS

public void doGetDDS(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     ReqState rs)
              throws java.io.IOException,
                     javax.servlet.ServletException
************************************************************************ Default handler for the client's DDS request. Requires the getDDS() method implemented by each server localization effort.

Once the DDS has been parsed and constrained it is sent to the requesting client.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
rs - The ReqState object for this client request.
Throws:
java.io.IOException
javax.servlet.ServletException

doGetDODS

public void doGetDODS(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      ReqState rs)
               throws java.io.IOException,
                      javax.servlet.ServletException
************************************************************************ Default handler for the client's data request. Requires the getDDS() method implemented by each server localization effort.

Once the DDS has been parsed, the data is read (using the class in the localized server factory etc.), compared to the constraint expression, and then sent to the client.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
rs - The ReqState object for this client request.
Throws:
java.io.IOException
javax.servlet.ServletException

doGetDIR

public void doGetDIR(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     ReqState rs)
              throws java.io.IOException,
                     javax.servlet.ServletException
************************************************************************ Default handler for the client's directory request.

Returns an html document to the client showing (a possibly pseudo) listing of the datasets available on the server in a directory listing format.

The bulk of this code resides in the class dods.servlet.dodsDIR and documentation may be found there.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsDIR

doGetVER

public void doGetVER(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response)
              throws java.io.IOException,
                     javax.servlet.ServletException
************************************************************************ Default handler for the client's version request.

Returns a plain text document with server version and DODS core version #'s

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException

doGetHELP

public void doGetHELP(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)
               throws java.io.IOException,
                      javax.servlet.ServletException
************************************************************************ Default handler for the client's help request.

Returns an html page of help info for the server

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException

badURL

public void badURL(javax.servlet.http.HttpServletRequest request,
                   javax.servlet.http.HttpServletResponse response)
            throws java.io.IOException,
                   javax.servlet.ServletException
************************************************************************ Sends an html document to the client explaining that they have used a poorly formed URL and then the help page...

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException

doGetASC

public void doGetASC(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     ReqState rs)
              throws java.io.IOException,
                     javax.servlet.ServletException
************************************************************************ Default handler for DODS ascii data requests. Returns the request data as a comma delimited ascii file. Note that this means that the more complex DODS structures such as Grids get flattened...

The bulk of this code resides in the class dods.servlet.dodsASCII and documentation may be found there.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsASCII

doGetINFO

public void doGetINFO(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      ReqState rs)
               throws java.io.IOException,
                      javax.servlet.ServletException
************************************************************************ Default handler for DODS info requests. Returns an html document describing the contents of the servers datasets.

The bulk of this code resides in the class dods.servlet.dodsINFO and documentation may be found there.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsINFO

doGetHTML

public void doGetHTML(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      ReqState rs)
               throws java.io.IOException,
                      javax.servlet.ServletException
************************************************************************ Default handler for DODS .html requests. Returns the DODS Web Interface (aka The Interface From Hell) to the client.

The bulk of this code resides in the class dods.servlet.dodsHTML and documentation may be found there.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsHTML

doGetCatalog

public void doGetCatalog(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response)
                  throws java.io.IOException,
                         javax.servlet.ServletException
************************************************************************ Default handler for DODS catalog.xml requests.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsHTML

printCatalog

protected void printCatalog(java.io.PrintWriter os)
                     throws java.io.IOException
Throws:
java.io.IOException

doGetStatus

public void doGetStatus(javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response)
                 throws java.io.IOException,
                        javax.servlet.ServletException
************************************************************************ Default handler for DODS status requests; not publically available, used only for debugging

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
dodsHTML

printStatus

protected void printStatus(java.io.PrintWriter os)
                    throws java.io.IOException
Throws:
java.io.IOException

probeRequest

public void probeRequest(javax.servlet.http.HttpServletRequest request)
************************************************************************ This is a bit of instrumentation that I kept around to let me look at the state of the incoming HttpServletRequest from the client. This method calls the get* methods of the request and prints the results to standard out.

Parameters:
request - The HttpServletRequest object to probe.

isTheClientCompressed

protected boolean isTheClientCompressed(javax.servlet.http.HttpServletRequest request)
Deprecated. This method has been encapsulated in the ReqState object and is no longer needed here.

************************************************************************* Evaluates a request object to determine if the client that sent the request accepts compressed return documents.

Parameters:
request - The HttpServletRequest sent by the client in question.
Returns:
True is the client accpets a compressed return document. False otherwise.
See Also:
ReqState

processDodsURL

protected ReqState processDodsURL(javax.servlet.http.HttpServletRequest request)
                           throws BadURLException
Deprecated. This method has been moved to the ReqState object and is no longer needed here.

************************************************************************* Processes an incoming HttpServletRequest and from it sets the cached values for:

Parameters:
request - The HttpServletRequest sent by the client in question.
Returns:
True if the URL wasn't junk, false otherwise.
Throws:
BadURLException
See Also:
ReqState

getServerName

public java.lang.String getServerName()
************************************************************************

In this (default) implementation of the getServerName() method we just get the name of the servlet and pass it back. If something different is required, override this method when implementing the getDDS() and getServerVersion() methods.

This is typically used by the getINFO() method to figure out if there is information specific to this server residing in the info directory that needs to be returned to the client as part of the .info response.

Returns:
A string containing the name of the servlet class that is running.

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws java.io.IOException,
                  javax.servlet.ServletException
*********************************************************************** Handles incoming requests from clients. Parses the request and determines what kind of DODS response the cleint is requesting. If the request is understood, then the appropriate handler method is called, otherwise an error is returned to the client.

This method is the entry point for DODSServlet. It uses the methods processDodsURL to extract the DODS URL information from the incoming client request. This DODS URL information is cached and made accessible through get and set methods.

After processDodsURL is called loadIniFile() is called to load configuration information from a .ini file,

If the standard behaviour of the servlet (extracting the DODS URL information from the client request, or loading the .ini file) then you should overload processDodsURL and loadIniFile() . We don't recommend overloading doGet() beacuse the logic contained there may change in our core and cause your server to behave unpredictably when future releases are installed.

Parameters:
request - The client's HttpServletRequest request object.
response - The server's HttpServletResponse response object.
Throws:
java.io.IOException
javax.servlet.ServletException
See Also:
processDodsURL(HttpServletRequest)