org.apache.pivot.web.server
Class QueryServlet

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by org.apache.pivot.web.server.QueryServlet
All Implemented Interfaces:
Serializable, Servlet, ServletConfig

public abstract class QueryServlet
extends HttpServlet

Abstract base class for web query servlets. It is the server counterpart to Query.

See Also:
Serialized Form

Nested Class Summary
static class QueryServlet.Credentials
          User credentials, which will be made availale if the servlet's authenticationRequired flag is set to true.
static class QueryServlet.Method
          Supported HTTP methods.
 
Constructor Summary
QueryServlet()
           
 
Method Summary
protected  void authorize()
          Authorizes the current request, and throws a LoginException if the request is not authorized.
protected  void doDelete()
          Called when an HTTP DELETE is received.
protected  void doDelete(HttpServletRequest request, HttpServletResponse response)
           
protected  Object doGet()
          Called when an HTTP GET is received.
protected  void doGet(HttpServletRequest request, HttpServletResponse response)
           
protected  void doHead(HttpServletRequest request, HttpServletResponse response)
           
protected  void doOptions(HttpServletRequest request, HttpServletResponse response)
           
protected  void doPost(HttpServletRequest request, HttpServletResponse response)
           
protected  URL doPost(Object value)
          Called when an HTTP POST is received.
protected  void doPut(HttpServletRequest request, HttpServletResponse response)
           
protected  void doPut(Object value)
          Called when an HTTP PUT is received.
protected  void doTrace(HttpServletRequest request, HttpServletResponse response)
           
 String getContextPath()
          Returns the portion of the request URI that indicates the context of the request.
 QueryServlet.Credentials getCredentials()
          Gets the authentication credentials that were extracted from the request.
 String getHostname()
          Gets the host name that was requested.
 QueryServlet.Method getMethod()
          Gets the HTTP method with which the current request was made.
 QueryDictionary getParameters()
          Returns the servlet's parameter dictionary, which holds the values passed in the HTTP request query string.
 int getPort()
          Returns the Internet Protocol (IP) port number of the interface on which the request was received.
 String getProtocol()
          Returns the name of the HTTP protocol that the request is using.
 String getQueryPath()
          Returns the portion of the request URI that occurs after the context path but preceding the query string.
 QueryDictionary getRequestHeaders()
          Returns the servlet's request header dictionary, which holds the HTTP request headers.
 QueryDictionary getResponseHeaders()
          Returns the servlet's response header dictionary, which holds the HTTP response headers that will be sent back to the client.
 boolean isAuthenticationRequired()
          Tells whether or not this servlet will require authentication data.
 boolean isDetermineContentLength()
          Tells whether this servlet is configured to always determine the content length of outgoing responses and set the Content-Length HTTP response header accordingly.
 boolean isSecure()
          Tells whether the request has been ecrypted over HTTPS.
protected abstract  Serializer<?> newSerializer()
          Creates a new serializer capable of serializing the objects that this servlet reads and writes.
protected  void service(HttpServletRequest request, HttpServletResponse response)
           
 void setAuthenticationRequired(boolean authenticationRequired)
          Sets whether or not this servlet will require authentication data.
 void setDetermineContentLength(boolean determineContentLength)
          Sets the value of the determineContentLength flag.
 
Methods inherited from class javax.servlet.http.HttpServlet
getLastModified, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

QueryServlet

public QueryServlet()
Method Detail

isDetermineContentLength

public boolean isDetermineContentLength()
Tells whether this servlet is configured to always determine the content length of outgoing responses and set the Content-Length HTTP response header accordingly. If this flag is false, it is up to the servlet's discretion as to when to set the Content-Length header (it will do so if it is trivially easy). If this is set to true, it will force the servlet to always set the header, but doing so will incur a performance penalty, as the servlet will be unable to stream the response directly to the HTTP output stream as it gets serialized.


setDetermineContentLength

public void setDetermineContentLength(boolean determineContentLength)
Sets the value of the determineContentLength flag.

See Also:
isDetermineContentLength()

isAuthenticationRequired

public boolean isAuthenticationRequired()
Tells whether or not this servlet will require authentication data. If set to true, and un-authenticated requests are received, the servlet will automatically respond with a request for authentication.


setAuthenticationRequired

public void setAuthenticationRequired(boolean authenticationRequired)
Sets whether or not this servlet will require authentication data. If set to true, and un-authenticated requests are received, the servlet will automatically respond with a request for authentication.


newSerializer

protected abstract Serializer<?> newSerializer()
Creates a new serializer capable of serializing the objects that this servlet reads and writes. For GET requests, this serializer will be used to write the response back to the client. For PUT and POST requests, this serializer will be used to read the object passed by the client.

Note: Since this servlet may be accessed by multiple threads, subclasses should not re-use servlets unless they do so in a thread-safe manner.

Returns:
A new serializer

getHostname

public String getHostname()
Gets the host name that was requested.


getContextPath

public String getContextPath()
Returns the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "".


getQueryPath

public String getQueryPath()
Returns the portion of the request URI that occurs after the context path but preceding the query string. It will start with a "/" character. For servlets in the default (root) context, this method returns the full path.


getPort

public int getPort()
Returns the Internet Protocol (IP) port number of the interface on which the request was received.


isSecure

public boolean isSecure()
Tells whether the request has been ecrypted over HTTPS.


getProtocol

public String getProtocol()
Returns the name of the HTTP protocol that the request is using.


getMethod

public QueryServlet.Method getMethod()
Gets the HTTP method with which the current request was made.


getCredentials

public QueryServlet.Credentials getCredentials()
Gets the authentication credentials that were extracted from the request. These are only available if the authenticationRequired flag is set to true.


getParameters

public QueryDictionary getParameters()
Returns the servlet's parameter dictionary, which holds the values passed in the HTTP request query string.


getRequestHeaders

public QueryDictionary getRequestHeaders()
Returns the servlet's request header dictionary, which holds the HTTP request headers.


getResponseHeaders

public QueryDictionary getResponseHeaders()
Returns the servlet's response header dictionary, which holds the HTTP response headers that will be sent back to the client.


doGet

protected Object doGet()
                throws ServletException,
                       ClientException
Called when an HTTP GET is received. This base method throws UnsupportedOperationException, which will cause an HTTP 405 (method not allowed) to be sent in the response. Subclasses should override this method if they wish to support GET requests.

Request parameters, and request/response headers are available to subclasses via the corresponding query dictionary.

Returns:
The object that was retrieved via the GET request. This object will be serialized by this servlet's serializer before being included in the HTTP response
Throws:
ServletException - If the server encounters an error while processing the request.
ClientException - If the client request is invalid in any way. This will cause the client to receive an HTTP 400 (bad request) response.
UnsupportedOperationException - If HTTP GET is not supported by the servlet.
See Also:
getParameters(), getRequestHeaders(), getResponseHeaders()

doPost

protected URL doPost(Object value)
              throws ServletException,
                     ClientException
Called when an HTTP POST is received. This base method throws UnsupportedOperationException, which will cause an HTTP 405 (method not allowed) to be sent in the response. Subclasses should override this method if they wish to support POST requests.

Request parameters, and request/response headers are available to subclasses via the corresponding query dictionary.

Parameters:
value - The object that is being posted by the client. This object will have been de-serialized from within the request by this servlet's serializer
Returns:
The URL identifying the location of the object that was posted. The semantics of this URL are up to the subclass to define
Throws:
ServletException - If the server encounters an error while processing the request.
ClientException - If the client request is invalid in any way. This will cause the client to receive an HTTP 400 (bad request) response.
UnsupportedOperationException - If HTTP POST is not supported by the servlet.
See Also:
getParameters(), getRequestHeaders(), getResponseHeaders()

doPut

protected void doPut(Object value)
              throws ServletException,
                     ClientException
Called when an HTTP PUT is received. This base method throws UnsupportedOperationException, which will cause an HTTP 405 (method not allowed) to be sent in the response. Subclasses should override this method if they wish to support PUT requests.

Request parameters, and request/response headers are available to subclasses via the corresponding query dictionary.

Parameters:
value - The object that is being updated by the client. This object will have been de-serialized from within the request by this servlet's serializer
Throws:
ServletException - If the server encounters an error while processing the request.
ClientException - If the client request is invalid in any way. This will cause the client to receive an HTTP 400 (bad request) response.
UnsupportedOperationException - If HTTP PUT is not supported by the servlet.
See Also:
getParameters(), getRequestHeaders(), getResponseHeaders()

doDelete

protected void doDelete()
                 throws ServletException,
                        ClientException
Called when an HTTP DELETE is received. This base method throws UnsupportedOperationException, which will cause an HTTP 405 (method not allowed) to be sent in the response. Subclasses should override this method if they wish to support DELETE requests.

Request parameters, and request/response headers are available to subclasses via the corresponding query dictionary.

Throws:
ServletException - If the server encounters an error while processing the request.
ClientException - If the client request is invalid in any way. This will cause the client to receive an HTTP 400 (bad request) response.
UnsupportedOperationException - If HTTP DELETE is not supported by the servlet.
See Also:
getParameters(), getRequestHeaders(), getResponseHeaders()

authorize

protected void authorize()
                  throws ServletException,
                         LoginException
Authorizes the current request, and throws a LoginException if the request is not authorized. This method will only be called if the authenticationRequired flag is set to true. Subclasses wishing to authorize the authenticated user credentials may override this method to perform that authorization. On the other hand, the authorize method of QueryServlet does nothing, so subclasses that wish to authenticate the request but not authorize it may simply not override this method.

This method is guaranteed to be called after the arguments and request properties have been made available.

Throws:
ServletException - If a servlet exception is thrown.
LoginException - If the request is not authorized.

service

protected void service(HttpServletRequest request,
                       HttpServletResponse response)
                throws IOException,
                       ServletException
Overrides:
service in class HttpServlet
Throws:
IOException
ServletException

doGet

protected final void doGet(HttpServletRequest request,
                           HttpServletResponse response)
                    throws IOException,
                           ServletException
Overrides:
doGet in class HttpServlet
Throws:
IOException
ServletException

doPost

protected final void doPost(HttpServletRequest request,
                            HttpServletResponse response)
                     throws IOException,
                            ServletException
Overrides:
doPost in class HttpServlet
Throws:
IOException
ServletException

doPut

protected final void doPut(HttpServletRequest request,
                           HttpServletResponse response)
                    throws IOException,
                           ServletException
Overrides:
doPut in class HttpServlet
Throws:
IOException
ServletException

doDelete

protected final void doDelete(HttpServletRequest request,
                              HttpServletResponse response)
                       throws IOException,
                              ServletException
Overrides:
doDelete in class HttpServlet
Throws:
IOException
ServletException

doHead

protected final void doHead(HttpServletRequest request,
                            HttpServletResponse response)
                     throws IOException,
                            ServletException
Overrides:
doHead in class HttpServlet
Throws:
IOException
ServletException

doOptions

protected final void doOptions(HttpServletRequest request,
                               HttpServletResponse response)
                        throws IOException,
                               ServletException
Overrides:
doOptions in class HttpServlet
Throws:
IOException
ServletException

doTrace

protected final void doTrace(HttpServletRequest request,
                             HttpServletResponse response)
                      throws IOException,
                             ServletException
Overrides:
doTrace in class HttpServlet
Throws:
IOException
ServletException