edu.ucsb.adl.middleware
Class ResultsServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--edu.ucsb.adl.middleware.ResultsServlet

All Implemented Interfaces:

java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public final class ResultsServlet

extends javax.servlet.http.HttpServlet

HTTP interface to the ADL results service. The results service can be accessed by an HTTP GET request containing two URL-encoded parameters: id, the ID of a result set; and op, the operation to perform on the result set. Some operations require additional parameters. If the URL of this servlet is S, then the possible operations, their semantics, and complete URLs are as follows:

S?id=R&op=delete

Deletes result set R. Returns status code 200 (OK), even if R is invalid.

S?id=R&op=get&index=I&views=list

Returns the result at index I within result set R. Result sets use zero-based indexing. list describes which of the result's standard metadata views to return; the possible views are "adl:access", "adl:browse", and "adl:bucket". Multiple views may be returned by listing them sequentially, separated by commas, as in "adl:browse,adl:bucket"; the order of the views is insignificant. The returned data has content type text/xml and uses UTF-8 encoding, and has the structure

<!DOCTYPE ADL-result [
<!ELEMENT ADL-result (identifier, ADL-bucket-report?,
    ADL-browse-report?, ADL-access-report?)>
<!ELEMENT identifier (#PCDATA)>
]>

S?id=R&op=multiget&from=F&to=T&views=list

Returns the results at indices F (inclusive) through T (exclusive) within result set R. Result sets use zero-based indexing. list is as described in the get operation above. The returned data has content type text/xml and uses UTF-8 encoding, and has the structure:

<!DOCTYPE ADL-result-list [
<!ELEMENT ADL-result-list (ADL-result*)>
]>

S?id=R&op=status

Returns the status of result set R. The returned data has content type text/xml and uses UTF-8 encoding, and has the structure

<!DOCTYPE ADL-result-set-status [
<!ELEMENT ADL-result-set-status (id, creation-time, result-count,
    (completion-time, total-result-count, exception?)?)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT creation-time (#PCDATA)>
<!ELEMENT result-count (#PCDATA)>
<!ELEMENT completion-time (#PCDATA)>
<!ELEMENT total-result-count (#PCDATA)>
<!ELEMENT exception (#PCDATA)>
]>

where

• id is the result set's ID, e.g., "135229823"
• creation-time is the result set's creation time in the semantics of System.currentTimeMillis, e.g., "948835216324"
• result-count is the current number of results in the result set, e.g., "327"
• completion-time is the result set's completion time in the semantics of System.currentTimeMillis, if the result set is complete
• total-result-count is the total result count (e.g., "392") if known or the string "unknown" otherwise, if the result set is complete
• exception is the exception that terminated the associated query if applicable, if the result set is complete.

S?id=R&op=wait

Identical to the status operation above, except that the operation blocks until the result set is complete.

S?id=R&op=get-query

Returns the XML query associated with result set R. The returned data has content type text/xml and uses UTF-8 encoding.

Service exceptions are caught and returned as HTTP errors. In particular, BadRequestException is mapped to 400 (bad request), NoAuthorizationException is mapped to 403 (forbidden), and InternalErrorException is mapped to 500 (internal server error).

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/ResultsServlet.java,v 1.10 2006/06/21 18:07:58 gjanee Exp $

$Log: ResultsServlet.java,v $ Revision 1.10 2006/06/21 18:07:58 gjanee
To make web browsers a little happier, servlets that formerly returned HTTP status code 204 (no content) now return status code 200 (OK) and return the plain text "DONE\n".

Revision 1.9 2004/09/22 03:00:26 gjanee
Rewrite to use new, centralized XML/HTML encoding functions.

Revision 1.8 2004/03/15 20:32:12 gjanee
Added the get-query operation.

Revision 1.7 2004/03/02 22:01:48 gjanee
If the middleware_configuration_file servlet initialization parameter is not available, we now look for it as a context-wide initialization parameter.

Revision 1.6 2003/06/09 18:39:52 gjanee
Query results are now Result objects, i.e., triplets of standard metadata views. The implication for this class is that views parameters were added to the get and multiget operations to allow specification of the returned views, and the returned XML formats were changed to <ADL-result> and <ADL-result-list>, respectively. Removed the scan_report_dtd_url initialization parameter, as it is no longer needed.

Revision 1.5 2001/11/16 17:41:33 gjanee
Internationalization support. All returned data now uses UTF-8 encoding.

Revision 1.4 2001/10/04 18:29:25 gjanee
To support the middleware being a web application, we now allow the location of the middleware configuration file to be specified relative to the web application directory.

Revision 1.3 2001/08/24 22:37:56 gjanee
Modified the multiget operation so that it now returns a single, well-formed XML document.

Revision 1.2 2001/02/15 18:36:46 gjanee
Minor upgrade to servlet API 2.2.

Revision 1.1 2000/04/20 19:38:39 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

See Also:

Serialized Form

Constructor Summary

ResultsServlet()
Creates a ResultsServlet.

Method Summary

void	destroy() Frees all resources held by the servlet.
void	doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) HTTP GET interface to the ADL results service.
void	init(javax.servlet.ServletConfig config) Initializes the servlet.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

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

ResultsServlet

public ResultsServlet()

Creates a ResultsServlet.

Method Detail

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException

Initializes the servlet.

Specified by:

init in interface javax.servlet.Servlet

Overrides:

init in class javax.servlet.GenericServlet

Parameters:

config - Must contain the following initialization parameter: middleware_configuration_file, the filename of the ADL middleware configuration file. If the filename is not absolute, it is interpreted relative to the middleware web application directory.

Throws:

javax.servlet.UnavailableException - If the initialization fails.

javax.servlet.ServletException

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws java.io.IOException

HTTP GET interface to the ADL results service. This method is multithread-safe.

Overrides:

doGet in class javax.servlet.http.HttpServlet

Parameters:

request - The HTTP request.

response - The HTTP response.

Throws:

java.io.IOException - On any I/O error.

destroy

public void destroy()

Frees all resources held by the servlet.

Specified by:

destroy in interface javax.servlet.Servlet

Overrides:

destroy in class javax.servlet.GenericServlet