com.oracle.iot.client.device.util

Class RequestDispatcher

java.lang.Object

com.oracle.iot.client.device.util.RequestDispatcher

public final class RequestDispatcher
extends java.lang.Object

RequestDispatcher is a utility that allows the caller to register handlers for requests coming from the IoT server. The RequestDispatcher handles all of the logic of matching the resource to a handler and invoking the handler.

Method Summary

Modifier and Type	Method and Description
ResponseMessage	dispatch(RequestMessage requestMessage) Match the request to a registered handler and invoke the handler.
static RequestDispatcher	getInstance() The RequestDispatcher is a singleton.
RequestHandler	getRequestHandler(java.lang.String endpointId, java.lang.String path) Lookup a RequestHandler for the given endpointId and path.
void	registerRequestHandler(java.lang.String endpointId, java.lang.String path, RequestHandler handler) Register a handler for the given endpoint and path.
void	unregisterRequestHandler(RequestHandler handler) Un-register the given handler for all endpoints and paths for which the handler may be registered.
void	unregisterRequestHandler(java.lang.String endpointId, java.lang.String path) Un-register the handler for the given endpoint and path.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static RequestDispatcher getInstance()

The RequestDispatcher is a singleton.

Returns:

The single instance of RequestDispatcher

registerRequestHandler

public void registerRequestHandler(java.lang.String endpointId,
                                   java.lang.String path,
                                   RequestHandler handler)

Register a handler for the given endpoint and path. If endpoint is null, empty, or a wildcard ("*"), then the handler is registered as being used for all endpoints. If path is null, empty, or a wildcard ("*") then the handler is registered as the handler for any requests that do not have a more specific handler. The handler parameter may not be null.

Registering a handler with registerRequestHandler("*", "*", handler) will register a default, catch-all handler. Note that this utility class already provides a reasonable default handler that can be replaced with this technique. The implementation ensures there is always a default handler.

Parameters:

endpointId - the endpoint id that has the given the resource path, or a wildcard ("*") for any endpoint.

path - the resource path, or a wildcard ("*") for any resource

handler - the handler to invoke for requests to this endpoint and path

Throws:

java.lang.IllegalArgumentException - if handler is null

unregisterRequestHandler

public void unregisterRequestHandler(java.lang.String endpointId,
                                     java.lang.String path)

Un-register the handler for the given endpoint and path. Either or both of the parameters may be a wildcard ("*"). Null or empty parameters are interpreted as a wildcard. Note that the wildcard is not used to match any endpoint or path, but is used to match a handler that was registered with the wildcard endpoint and/or path. Thus, a handler registered by calling registerRequestHandler("0-AB", "resource", handler) will not be un-registered by calling unregisterRequestHandler("*", "resource"). Nor will calling unregisterRequestHandler("0-AB", "*") result in un-registering all handlers for endpoint "0-AB". In short, the arguments to registerRequestHandler should match the arguments to unregisterRequestHandler.

A default handler can be registered by calling registerRequestHandler("*", "*", handler). Calling unregisterRequestHandler("*", "*") will restore the default handler. The implementation ensures there is always a default handler.

Parameters:

endpointId - the endpoint id that has the given the resource path, or a wildcard ("*").

path - the resource path, or a wildcard ("*")

unregisterRequestHandler

public void unregisterRequestHandler(RequestHandler handler)

Un-register the given handler for all endpoints and paths for which the handler may be registered. The handler parameter may not be null.

Parameters:

handler - the handler to un-register

dispatch

public ResponseMessage dispatch(RequestMessage requestMessage)

Match the request to a registered handler and invoke the handler.

Parameters:

requestMessage - The request message to be dispatched

Returns:

The return value of the invoked handler. If the invoked handler throws an exception or returns null, a reasonable response will be returned by this utility. This method will not return null.

Throws:

java.lang.IllegalArgumentException - if requestMessage is null

getRequestHandler

public RequestHandler getRequestHandler(java.lang.String endpointId,
                                        java.lang.String path)

Lookup a RequestHandler for the given endpointId and path. The lookup will return the most specific handler for the endpointId and path. If there is not a specific match for endpointId, the lookup will match try to match ("*", path). Failing that, the lookup will return a handler for ("*", "*"), or the default handler if no handler for ("*","*") has been registered. Will not return null.

Parameters:

endpointId - the endpoint id that has the given the resource path, or a wildcard ("*").

path - the resource path, or a wildcard ("*")

Returns:

The RequestHandler for the given endpointId and path.