water.api

Class RequestServer

java.lang.Object

water.NanoHTTPD

water.api.RequestServer

public class RequestServer
extends NanoHTTPD

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 parameterized 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:

a class which contains HTTP request handler methods and other helpers, a class which provides a stable external representation for entities and request parameters, registers a specific handler method for the supplied URI pattern and HTTP method (GET, POST, DELETE, PUT)

Nested Class Summary

Nested classes/interfaces inherited from class water.NanoHTTPD

NanoHTTPD.Response

Field Summary

Fields

Modifier and Type	Field and Description
static int	H2O_REST_API_VERSION
static RequestServer	SERVER

Fields inherited from class water.NanoHTTPD

HTTP_BADREQUEST, HTTP_FORBIDDEN, HTTP_INTERNALERROR, HTTP_NOTFOUND, HTTP_NOTIMPLEMENTED, HTTP_NOTMODIFIED, HTTP_OK, HTTP_PARTIALCONTENT, HTTP_RANGE_NOT_SATISFIABLE, HTTP_REDIRECT, HTTP_TOOLONGREQUEST, HTTP_UNAUTHORIZED, MIME_DEFAULT_BINARY, MIME_HTML, MIME_JSON, MIME_PLAINTEXT, MIME_XML, myOut

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.String	addToNavbar(water.api.Route route, java.lang.String base_url, java.lang.String name, java.lang.String category)
static void	alwaysLogRequest(java.lang.String uri, java.lang.String method, java.util.Properties parms)
protected static water.api.Route	lookup(java.lang.String http_method, java.lang.String uri)
static int	numRoutes()
static water.api.Route	register(java.lang.String uri_pattern, java.lang.String http_method, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String summary) Deprecated.
static water.api.Route	register(java.lang.String uri_pattern, java.lang.String http_method, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String[] path_params, java.lang.String summary) Deprecated.
static water.api.Route	register(java.lang.String uri_pattern, java.lang.String http_method, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String doc_method, java.lang.String summary) Register an HTTP request handler for a given URI pattern, with no path parameters.
static water.api.Route	register(java.lang.String uri_pattern_raw, java.lang.String http_method, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String doc_method, java.lang.String[] path_params, java.lang.String summary) Register an HTTP request handler method for a given URL pattern, with parameters extracted from the URI.
static water.api.Route	register(java.lang.String uri_pattern_raw, java.lang.String http_method, java.lang.Class<? extends Handler> handler_class, java.lang.String handler_method, java.lang.String doc_method, java.lang.String[] path_params, java.lang.String summary, HandlerFactory handler_factory) Register an HTTP request handler method for a given URL pattern, with parameters extracted from the URI.
static java.util.Collection<water.api.Route>	routes()
NanoHTTPD.Response	serve(java.lang.String uri, java.lang.String method, java.util.Properties header, java.util.Properties parms) Override this to customize the server.
static java.lang.Runnable	start()

Methods inherited from class water.NanoHTTPD

main, serveFile, stop

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

SERVER

public static RequestServer SERVER

Method Detail

numRoutes

public static final int numRoutes()

routes

public static final java.util.Collection<water.api.Route> routes()

register

@Deprecated
public static water.api.Route register(java.lang.String uri_pattern,
                                  java.lang.String http_method,
                                  java.lang.Class<? extends Handler> handler_class,
                                  java.lang.String handler_method,
                                  java.lang.String summary)

Deprecated.

register

@Deprecated
public static water.api.Route register(java.lang.String uri_pattern,
                                  java.lang.String http_method,
                                  java.lang.Class<? extends Handler> handler_class,
                                  java.lang.String handler_method,
                                  java.lang.String[] path_params,
                                  java.lang.String summary)

Deprecated.

register

public static water.api.Route register(java.lang.String uri_pattern,
                       java.lang.String http_method,
                       java.lang.Class<? extends Handler> handler_class,
                       java.lang.String handler_method,
                       java.lang.String doc_method,
                       java.lang.String summary)

Register an HTTP request handler for a given URI pattern, with no path parameters.

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

Parameters:

uri_pattern - regular expression which matches the URL path for this request handler; parameters that are embedded in the path must be captured with <code>(?<parm>.*)</code> syntax

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

handler_class - class which contains the handler method

handler_method - name of the handler method

doc_method - name of a method which returns GitHub Flavored Markdown documentation for the request

Returns:

the Route for this request

See Also:

Route, RequestServer

register

public static water.api.Route register(java.lang.String uri_pattern_raw,
                       java.lang.String http_method,
                       java.lang.Class<? extends Handler> handler_class,
                       java.lang.String handler_method,
                       java.lang.String doc_method,
                       java.lang.String[] path_params,
                       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:

uri_pattern_raw - regular expression which matches the URL path for this request handler; parameters that are embedded in the path must be captured with <code>(?<parm>.*)</code> syntax

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

handler_class - class which contains the handler method

handler_method - name of the handler method

doc_method - name of a method which returns GitHub Flavored Markdown documentation for the request

path_params - list of parameter names to extract from the uri_pattern; they are matched by name from the named pattern capture group

summary - short help string which summarizes the functionality of this endpoint

Returns:

the Route for this request

See Also:

Route, RequestServer

register

public static water.api.Route register(java.lang.String uri_pattern_raw,
                       java.lang.String http_method,
                       java.lang.Class<? extends Handler> handler_class,
                       java.lang.String handler_method,
                       java.lang.String doc_method,
                       java.lang.String[] path_params,
                       java.lang.String summary,
                       HandlerFactory handler_factory)

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:

uri_pattern_raw - regular expression which matches the URL path for this request handler; parameters that are embedded in the path must be captured with <code>(?<parm>.*)</code> syntax

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

handler_class - class which contains the handler method

handler_method - name of the handler method

doc_method - name of a method which returns GitHub Flavored Markdown documentation for the request

path_params - list of parameter names to extract from the uri_pattern; they are matched by name from the named pattern capture group

summary - short help string which summarizes the functionality of this endpoint

handler_factory - factory to create instance of handler

Returns:

the Route for this request

See Also:

Route, RequestServer

lookup

protected static water.api.Route lookup(java.lang.String http_method,
                     java.lang.String uri)

start

public static java.lang.Runnable start()

alwaysLogRequest

public static void alwaysLogRequest(java.lang.String uri,
                    java.lang.String method,
                    java.util.Properties parms)

serve

public NanoHTTPD.Response serve(java.lang.String uri,
                       java.lang.String method,
                       java.util.Properties header,
                       java.util.Properties parms)

Description copied from class: NanoHTTPD

Override this to customize the server.

(By default, this delegates to serveFile() and allows directory listing.)

Overrides:

serve in class NanoHTTPD

Parameters:

uri - Percent-decoded URI without parameters, for example "/index.cgi"

method - "GET", "POST" etc.

header - Header entries, percent decoded

parms - Parsed, percent decoded parameters from URI and, in case of POST, data.

Returns:

HTTP response, see class Response for details

addToNavbar

public static java.lang.String addToNavbar(water.api.Route route,
                           java.lang.String base_url,
                           java.lang.String name,
                           java.lang.String category)