dods.servlet
Class DODSServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--dods.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:

#getDDS(String), #loadIniFile(), processDodsURL(HttpServletRequest), Serialized Form

Constructor Summary

DODSServlet()

Method Summary

void	anyExceptionHandler(java.lang.Throwable e, javax.servlet.http.HttpServletResponse response, requestState 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, requestState 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, requestState rs) Default handler for the client's DAS request.
void	doGetDDS(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, requestState rs) Default handler for the client's DDS request.
void	doGetDIR(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, requestState rs) Default handler for the client's directory request.
void	doGetDODS(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, requestState 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, requestState rs) Default handler for DODS .html requests.
void	doGetINFO(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, requestState 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(requestState rs) In this (default) implementation of the getDAS() method a locally cached DAS is retrieved and parsed.
protected abstract GuardedDataset	getDataset(requestState 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) Evaluates a request object to determine if the client that sent the request accepts compressed return documents.
java.io.DataInputStream	openCachedDAS(requestState rs) Opens a DAS cached on local disk.
java.io.DataInputStream	openCachedDDS(requestState 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 requestState	processDodsURL(javax.servlet.http.HttpServletRequest request) Processes an incoming HttpServletRequest and from it sets the cached values for: dataSet The data set name.(Accessible using setDataSet() and getDataSet()) CE The constraint expression.(Accessible using setCE() and getCE()) requestSuffix The request suffix, used by DODS to indicate the type of response desired by the client.
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(requestState 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:

• Make a new ServerFactory (aka BaseTypeFactory) for the dataset requested.
• Instantiate a ServerDDS using the ServerFactory and populate it (this could be accomplished by just opening a (cached?) DDS in a file and parsing it)
• Return this freshly minted ServerDDS object (to the servlet code where it is used.)

Returns:

The ServerDDS object all parsed and ready to roll.

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...

Overrides:

init in class javax.servlet.GenericServlet

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,
                                requestState rs)

Sends an error to the client.

Parameters:

response - The HttpServletResponse for the client.

getDAS

protected DAS getDAS(requestState 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:

• Instantiates the DAS for the indicated (passed) dataset and populates it. This is accomplished in the default implementation by opening a (cached?) DAS stored in a file and parsing it. In a different implementation it could be created dynamically.
• Returns this freshly minted DAS object. (to the servlet code where it is used.)

Returns:

The DAS object for the data set specified in the parameter dataSet

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.

java.io.IOException

javax.servlet.ServletException

openCachedDDS

public java.io.DataInputStream openCachedDDS(requestState 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.

Returns:

An open DataInputStream from which the DDS can be read.

Throws:

DODSException

See Also:

#loadIniFile()

openCachedDAS

public java.io.DataInputStream openCachedDAS(requestState 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.

Returns:

An open DataInputStream from which the DAS can be read.

Throws:

java.io.FileNotFoundException

See Also:

#loadIniFile()

doGetDAS

public void doGetDAS(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     requestState 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.

java.io.IOException

javax.servlet.ServletException

doGetDDS

public void doGetDDS(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     requestState 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.

java.io.IOException

javax.servlet.ServletException

doGetDODS

public void doGetDODS(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      requestState 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.

java.io.IOException

javax.servlet.ServletException

doGetDIR

public void doGetDIR(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     requestState 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.

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.

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.

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.

java.io.IOException

javax.servlet.ServletException

doGetASC

public void doGetASC(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     requestState 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.

java.io.IOException

javax.servlet.ServletException

See Also:

dodsASCII

doGetINFO

public void doGetINFO(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      requestState 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.

java.io.IOException

javax.servlet.ServletException

See Also:

dodsINFO

doGetHTML

public void doGetHTML(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response,
                      requestState 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.

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.

java.io.IOException

javax.servlet.ServletException

See Also:

dodsHTML

printCatalog

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

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.

java.io.IOException

javax.servlet.ServletException

See Also:

dodsHTML

printStatus

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

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)

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.

processDodsURL

protected requestState processDodsURL(javax.servlet.http.HttpServletRequest request)

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

• dataSet The data set name.(Accessible using setDataSet() and getDataSet())
• CE The constraint expression.(Accessible using setCE() and getCE())
• requestSuffix The request suffix, used by DODS to indicate the type of response desired by the client. (Accessible using setRequestSuffix() and getRequestSuffix())

Parameters:

request - The HttpServletRequest sent by the client in question.

See Also:

#getDataSet(), #setDataSet(String), #getCE(), #setCE(String), #getRequestSuffix(), #setRequestSuffix(String)

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.

Overrides:

doGet in class javax.servlet.http.HttpServlet

Parameters:

request - The client's HttpServletRequest request object.

response - The server's HttpServletResponse response object.

java.io.IOException

javax.servlet.ServletException

See Also:

processDodsURL(HttpServletRequest), #getDataSet(), #setDataSet(String), #getCE(), #setCE(String), #getRequestSuffix(), #setRequestSuffix(String), #loadIniFile()