water.api

Class RequestServer

java.lang.Object

javax.servlet.GenericServlet

javax.servlet.http.HttpServlet

water.api.RequestServer

All Implemented Interfaces:

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

public class RequestServer
extends javax.servlet.http.HttpServlet

This is a simple web server which accepts HTTP requests and routes them to methods in Handler classes for processing. Schema classes are used to provide a more stable external JSON interface while allowing the implementation to evolve rapidly. As part of request handling the framework translates back and forth between the stable external representation of objects (Schema) and the less stable internal classes.

Request routing is done by searching a list of registered handlers, in order of registration, for a handler whose path regex matches the request URI and whose HTTP method (GET, POST, DELETE...) matches the request's method. If none is found an HTTP 404 is returned.

A Handler class is parametrized by the kind of Schema that it accepts for request handling, as well as the internal implementation class (Iced class) that the Schema translates from and to. Handler methods are allowed to return other Schema types than in the type parameter if that makes sense for a given request. For example, a prediction (scoring) call on a Model might return a Frame schema.

When an HTTP request is accepted the framework does the following steps:

1. searches the registered handler methods for a matching URL and HTTP method
2. collects any parameters which are captured from the URI and adds them to the map of HTTP query parameters
3. creates an instance of the correct Handler class and calls handle() on it, passing the version, route and params
4. Handler.handle() creates the correct Schema object given the version and calls fillFromParms(params) on it
5. calls schema.createImpl() to create a schema-independent "back end" object
6. dispatches to the handler method, passing in the schema-independent impl object and returning the result Schema object

See Also:

Handler, RegisterV3Api, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RequestServer.DummyRestApiContext Dummy Rest API context which is redirecting calls to static method API.
static interface	RequestServer.HttpLogFilter Create a new HttpLogFilter.
static class	RequestServer.LogFilterLevel

Field Summary

Fields

Modifier and Type	Field and Description
static int	H2O_REST_API_VERSION
static java.lang.String	HTTP_ACCEPTED Some HTTP response status codes
static java.lang.String	HTTP_BAD_METHOD Some HTTP response status codes
static java.lang.String	HTTP_BAD_REQUEST Some HTTP response status codes
static java.lang.String	HTTP_CREATED Some HTTP response status codes
static java.lang.String	HTTP_FORBIDDEN Some HTTP response status codes
static java.lang.String	HTTP_INTERNAL_ERROR Some HTTP response status codes
static java.lang.String	HTTP_NO_CONTENT Some HTTP response status codes
static java.lang.String	HTTP_NOT_FOUND Some HTTP response status codes
static java.lang.String	HTTP_NOT_IMPLEMENTED Some HTTP response status codes
static java.lang.String	HTTP_NOT_MODIFIED Some HTTP response status codes
static java.lang.String	HTTP_OK Some HTTP response status codes
static java.lang.String	HTTP_PARTIAL_CONTENT Some HTTP response status codes
static java.lang.String	HTTP_PRECONDITION_FAILED Some HTTP response status codes
static java.lang.String	HTTP_RANGE_NOT_SATISFIABLE Some HTTP response status codes
static java.lang.String	HTTP_REDIRECT Some HTTP response status codes
static java.lang.String	HTTP_SERVICE_NOT_AVAILABLE Some HTTP response status codes
static java.lang.String	HTTP_TEAPOT Some HTTP response status codes
static java.lang.String	HTTP_THROTTLE Some HTTP response status codes
static java.lang.String	HTTP_TOO_LONG_REQUEST Some HTTP response status codes
static java.lang.String	HTTP_UNAUTHORIZED Some HTTP response status codes
static java.lang.String	MIME_CSS Common mime types for dynamic content
static java.lang.String	MIME_DEFAULT_BINARY Common mime types for dynamic content
static java.lang.String	MIME_GIF Common mime types for dynamic content
static java.lang.String	MIME_HTML Common mime types for dynamic content
static java.lang.String	MIME_JPEG Common mime types for dynamic content
static java.lang.String	MIME_JS Common mime types for dynamic content
static java.lang.String	MIME_JSON Common mime types for dynamic content
static java.lang.String	MIME_PLAINTEXT Common mime types for dynamic content
static java.lang.String	MIME_PNG Common mime types for dynamic content
static java.lang.String	MIME_SVG Common mime types for dynamic content
static java.lang.String	MIME_WOFF Common mime types for dynamic content
static java.lang.String	MIME_XML Common mime types for dynamic content

Constructor Summary

Constructors

Constructor and Description
RequestServer()

Method Summary

Modifier and Type	Method and Description
static RequestServer.HttpLogFilter	defaultFilter() Provide the default filters for H2O's HTTP logging.
protected void	doDelete(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
void	doGeneric(java.lang.String method, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Top-level dispatch handling
protected void	doGet(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
protected void	doHead(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
protected void	doOptions(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
protected void	doPost(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
protected void	doPut(javax.servlet.http.HttpServletRequest rq, javax.servlet.http.HttpServletResponse rs)
protected void	doTrace(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
static Route	lookupRoute(RequestUri uri)
static int	numRoutes()
static int	numRoutes(int version) Calculates number of routes having the specified version.
static Route	registerEndpoint(java.lang.String method_uri, java.lang.Class<? extends RestApiHandler> handler_clz) Register an HTTP request handler for the given URL pattern.
static Route	registerEndpoint(java.lang.String api_name, java.lang.String method_uri, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String summary) Register an HTTP request handler method for a given URL pattern, with parameters extracted from the URI.
static Route	registerEndpoint(java.lang.String api_name, java.lang.String http_method, java.lang.String url, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String summary, HandlerFactory handler_factory)
static java.util.ArrayList<Route>	routes()
static NanoResponse	serve(java.lang.String url, java.lang.String method, java.util.Properties header, java.util.Properties parms, java.lang.String post_body) Subsequent handling of the dispatch
static void	setFilters(RequestServer.HttpLogFilter... filters)

Methods inherited from class javax.servlet.http.HttpServlet

getLastModified, service, 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

Field Detail

H2O_REST_API_VERSION

public static final int H2O_REST_API_VERSION

See Also:

Constant Field Values

HTTP_OK

public static final java.lang.String HTTP_OK

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_CREATED

public static final java.lang.String HTTP_CREATED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_ACCEPTED

public static final java.lang.String HTTP_ACCEPTED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_NO_CONTENT

public static final java.lang.String HTTP_NO_CONTENT

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_PARTIAL_CONTENT

public static final java.lang.String HTTP_PARTIAL_CONTENT

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_REDIRECT

public static final java.lang.String HTTP_REDIRECT

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_NOT_MODIFIED

public static final java.lang.String HTTP_NOT_MODIFIED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_BAD_REQUEST

public static final java.lang.String HTTP_BAD_REQUEST

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_UNAUTHORIZED

public static final java.lang.String HTTP_UNAUTHORIZED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_FORBIDDEN

public static final java.lang.String HTTP_FORBIDDEN

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_NOT_FOUND

public static final java.lang.String HTTP_NOT_FOUND

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_BAD_METHOD

public static final java.lang.String HTTP_BAD_METHOD

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_PRECONDITION_FAILED

public static final java.lang.String HTTP_PRECONDITION_FAILED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_TOO_LONG_REQUEST

public static final java.lang.String HTTP_TOO_LONG_REQUEST

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_RANGE_NOT_SATISFIABLE

public static final java.lang.String HTTP_RANGE_NOT_SATISFIABLE

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_TEAPOT

public static final java.lang.String HTTP_TEAPOT

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_THROTTLE

public static final java.lang.String HTTP_THROTTLE

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_INTERNAL_ERROR

public static final java.lang.String HTTP_INTERNAL_ERROR

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_NOT_IMPLEMENTED

public static final java.lang.String HTTP_NOT_IMPLEMENTED

Some HTTP response status codes

See Also:

Constant Field Values

HTTP_SERVICE_NOT_AVAILABLE

public static final java.lang.String HTTP_SERVICE_NOT_AVAILABLE

Some HTTP response status codes

See Also:

Constant Field Values

MIME_PLAINTEXT

public static final java.lang.String MIME_PLAINTEXT

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_HTML

public static final java.lang.String MIME_HTML

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_CSS

public static final java.lang.String MIME_CSS

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_JSON

public static final java.lang.String MIME_JSON

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_JS

public static final java.lang.String MIME_JS

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_JPEG

public static final java.lang.String MIME_JPEG

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_PNG

public static final java.lang.String MIME_PNG

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_SVG

public static final java.lang.String MIME_SVG

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_GIF

public static final java.lang.String MIME_GIF

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_WOFF

public static final java.lang.String MIME_WOFF

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_DEFAULT_BINARY

public static final java.lang.String MIME_DEFAULT_BINARY

Common mime types for dynamic content

See Also:

Constant Field Values

MIME_XML

public static final java.lang.String MIME_XML

Common mime types for dynamic content

See Also:

Constant Field Values

Constructor Detail

RequestServer

public RequestServer()

Method Detail

numRoutes

public static int numRoutes()

routes

public static java.util.ArrayList<Route> routes()

lookupRoute

public static Route lookupRoute(RequestUri uri)

setFilters

public static void setFilters(RequestServer.HttpLogFilter... filters)

numRoutes

public static int numRoutes(int version)

Calculates number of routes having the specified version.

registerEndpoint

public static Route registerEndpoint(java.lang.String api_name,
                                     java.lang.String method_uri,
                                     java.lang.Class<? extends Handler> handler_class,
                                     java.lang.String handler_method,
                                     java.lang.String summary)

Register an HTTP request handler method for a given URL pattern, with parameters extracted from the URI.

URIs which match this pattern will have their parameters collected from the path and from the query params

Parameters:

api_name - suggested method name for this endpoint in the external API library. These names should be unique. If null, the api_name will be created from the class name and the handler method name.

method_uri - combined method / url pattern of the request, e.g.: "GET /3/Jobs/{job_id}"

handler_class - class which contains the handler method

handler_method - name of the handler method

summary - help string which explains the functionality of this endpoint

Returns:

the Route for this request

See Also:

Route, RequestServer

registerEndpoint

public static Route registerEndpoint(java.lang.String api_name,
                                     java.lang.String http_method,
                                     java.lang.String url,
                                     java.lang.Class<? extends Handler> handler_class,
                                     java.lang.String handler_method,
                                     java.lang.String summary,
                                     HandlerFactory handler_factory)

Parameters:

api_name - suggested method name for this endpoint in the external API library. These names should be unique. If null, the api_name will be created from the class name and the handler method name.

http_method - HTTP verb (GET, POST, DELETE) this handler will accept

url - url path, possibly containing placeholders in curly braces, e.g: "/3/DKV/{key}"

handler_class - class which contains the handler method

handler_method - name of the handler method

summary - help string which explains the functionality of this endpoint

handler_factory - factory to create instance of handler (used by Sparkling Water)

Returns:

the Route for this request

registerEndpoint

public static Route registerEndpoint(java.lang.String method_uri,
                                     java.lang.Class<? extends RestApiHandler> handler_clz)

Register an HTTP request handler for the given URL pattern.

Parameters:

method_uri - combined method/url pattern of the endpoint, for example: "GET /3/Jobs/{job_id}"

handler_clz - class of the handler (should inherit from RestApiHandler).

doTrace

protected void doTrace(javax.servlet.http.HttpServletRequest req,
                       javax.servlet.http.HttpServletResponse resp)

Overrides:

doTrace in class javax.servlet.http.HttpServlet

doGet

protected void doGet(javax.servlet.http.HttpServletRequest rq,
                     javax.servlet.http.HttpServletResponse rs)

Overrides:

doGet in class javax.servlet.http.HttpServlet

doPut

protected void doPut(javax.servlet.http.HttpServletRequest rq,
                     javax.servlet.http.HttpServletResponse rs)

Overrides:

doPut in class javax.servlet.http.HttpServlet

doPost

protected void doPost(javax.servlet.http.HttpServletRequest rq,
                      javax.servlet.http.HttpServletResponse rs)

Overrides:

doPost in class javax.servlet.http.HttpServlet

doHead

protected void doHead(javax.servlet.http.HttpServletRequest rq,
                      javax.servlet.http.HttpServletResponse rs)

Overrides:

doHead in class javax.servlet.http.HttpServlet

doDelete

protected void doDelete(javax.servlet.http.HttpServletRequest rq,
                        javax.servlet.http.HttpServletResponse rs)

Overrides:

doDelete in class javax.servlet.http.HttpServlet

doOptions

protected void doOptions(javax.servlet.http.HttpServletRequest rq,
                         javax.servlet.http.HttpServletResponse rs)

Overrides:

doOptions in class javax.servlet.http.HttpServlet

doGeneric

public void doGeneric(java.lang.String method,
                      javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)

Top-level dispatch handling

serve

public static NanoResponse serve(java.lang.String url,
                                 java.lang.String method,
                                 java.util.Properties header,
                                 java.util.Properties parms,
                                 java.lang.String post_body)

Subsequent handling of the dispatch

defaultFilter

public static RequestServer.HttpLogFilter defaultFilter()

Provide the default filters for H2O's HTTP logging.

Returns:

an array of HttpLogFilter instances