io.inversion

Class Engine

java.lang.Object

io.inversion.Rule<Engine>

io.inversion.Engine

All Implemented Interfaces:

java.lang.Comparable<Engine>

public class Engine
extends Rule<Engine>

Matches inbound Request Url paths to an Api Endpoint and executes associated Actions.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Engine.EngineListener Receives Engine and Api lifecycle, per request and per error callback notifications.

Nested classes/interfaces inherited from class io.inversion.Rule

Rule.RuleMatcher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<Api>	apis The Apis being service by this Engine
protected java.lang.String	configPath Optional override for the configPath sys/env prop used by Config to locate configuration property files
protected java.lang.String	configProfile Optional override for the sys/env prop used by Config to determine which profile specific configuration property files to load
protected java.lang.String	corsAllowHeaders Base value for the CORS "Access-Control-Allow-Headers" response header.
protected Response	lastResponse The last Response served by this Engine, primarily used for writing test cases.
protected java.util.List<Engine.EngineListener>	listeners Listeners that will receive Engine and Api lifecycle, request, and error callbacks.

Fields inherited from class io.inversion.Rule

configMap, configStr, excludeMatchers, excludeOn, includeMatchers, includeOn, log, name, order

Constructor Summary

Constructors

Constructor and Description
Engine()
Engine(Api... apis)

Method Summary

Modifier and Type	Method and Description
Response	delete(java.lang.String url) Convenience overloading of #service(Request, Response) to run a REST DELETE Request on this Engine.
Response	delete(java.lang.String url, JSArray hrefs) Convenience overloading of #service(Request, Response) to run a REST DELETE Request on this Engine.
Response	get(java.lang.String url) Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.
Response	get(java.lang.String url, java.util.List queryTerms) Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.
Response	get(java.lang.String url, java.util.Map<java.lang.String,java.lang.String> params) Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.
Api	getApi(java.lang.String apiName)
java.util.List<Api>	getApis()
java.lang.String	getConfigPath()
java.lang.String	getConfigProfile()
Response	getLastResponse()
java.net.URL	getResource(java.lang.String name)
boolean	isStarted()
Response	patch(java.lang.String url, JSNode body) Convenience overloading of #service(Request, Response) to run a REST PATCH Request on this Engine.
Response	post(java.lang.String url, JSNode body) Convenience overloading of #service(Request, Response) to run a REST POST Request on this Engine.
Response	put(java.lang.String url, JSNode body) Convenience overloading of #service(Request, Response) to run a REST PUT Request on this Engine.
void	removeApi(Api api) Removes the api, notifies EngineListeners and calls api.shutdown().
Chain	service(Request req, Response res) The main entry point for processing a Request and generating Response content.
Response	service(java.lang.String method, java.lang.String url) Convenience overloading of #service(Request, Response)
Response	service(java.lang.String method, java.lang.String url, java.lang.String body) Convenience overloading of #service(Request, Response)
Response	service(java.lang.String method, java.lang.String url, java.lang.String body, java.util.Map<java.lang.String,java.lang.String> params) Convenience overloading of #service(Request, Response)
void	shutdown() Removes all Apis and notifies listeners.onShutdown
protected void	shutdownApi(Api api)
Engine	startup() Runs the Configurator and calls startupApi for each Api.
protected void	startup0() Convenient pre-startup hook for subclasses guaranteed to only be called once.
protected void	startupApi(Api api)
Engine	withAllowHeaders(java.lang.String allowHeaders)
Engine	withApi(Api api)
Engine	withConfigPath(java.lang.String configPath)
Engine	withConfigProfile(java.lang.String configProfile)
Engine	withEngineListener(Engine.EngineListener listener) Registers listener to receive Engine, Api, request and error callbacks.

Methods inherited from class io.inversion.Rule

checkLazyConfig, compareTo, doLazyConfig, getAllExcludePaths, getAllIncludePaths, getConfig, getConfig, getConfigKeys, getDefaultIncludeMatch, getExcludeMatchers, getIncludeMatchers, getName, getOrder, match, matches, matches, toString, withConfig, withExcludeOn, withExcludeOn, withExcludeOn, withIncludeOn, withIncludeOn, withIncludeOn, withName, withOrder

Methods inherited from class java.lang.Object

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

Field Detail

listeners

protected final transient java.util.List<Engine.EngineListener> listeners

Listeners that will receive Engine and Api lifecycle, request, and error callbacks.

lastResponse

protected transient volatile Response lastResponse

The last Response served by this Engine, primarily used for writing test cases.

apis

protected java.util.List<Api> apis

The Apis being service by this Engine

corsAllowHeaders

protected java.lang.String corsAllowHeaders

Base value for the CORS "Access-Control-Allow-Headers" response header.

Values from the request "Access-Control-Request-Header" header are concatenated to this resulting in the final value of "Access-Control-Allow-Headers" sent in the response.

Unless you are really doing something specific with browser security you probably won't need to customize this list.

configPath

protected java.lang.String configPath

Optional override for the configPath sys/env prop used by Config to locate configuration property files

See Also:

Config.loadConfiguration(String, String)

configProfile

protected java.lang.String configProfile

Optional override for the sys/env prop used by Config to determine which profile specific configuration property files to load

See Also:

Config.loadConfiguration(String, String)

Constructor Detail

Engine

public Engine()

Engine

public Engine(Api... apis)

Method Detail

startup0

protected void startup0()

Convenient pre-startup hook for subclasses guaranteed to only be called once.

Called after starting has been set to true but before the Configurator is run or any Apis have been started.

startup

public Engine startup()

Runs the Configurator and calls startupApi for each Api.

An Engine can only be started once. Any calls to startup after the initial call will not have any affect.

Returns:

this Engine

shutdown

public void shutdown()

Removes all Apis and notifies listeners.onShutdown

get

public Response get(java.lang.String url)

Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

GET requests for a specific resource should return 200 of 404. GET requests with query string search conditions should return 200 even if the search did not yield any results.

Parameters:

url - the url that will be serviced by this Engine

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbGetAction

get

public Response get(java.lang.String url,
                    java.util.Map<java.lang.String,java.lang.String> params)

Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

GET requests for a specific resource should return 200 of 404. GET requests with query string search conditions should return 200 even if the search did not yield any results.

Parameters:

url - the url that will be serviced by this Engine

params - additional key/value pairs to add to the url query string

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbGetAction

get

public Response get(java.lang.String url,
                    java.util.List queryTerms)

Convenience overloading of #service(Request, Response) to run a REST GET Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

GET requests for a specific resource should return 200 of 404. GET requests with query string search conditions should return 200 even if the search did not yield any results.

Parameters:

url - the url that will be serviced by this Engine

queryTerms - additional keys (no values) to add to the url query string

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbGetAction

post

public Response post(java.lang.String url,
                     JSNode body)

Convenience overloading of #service(Request, Response) to run a REST POST Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Successful POSTs that create a new resource should return a 201.

Parameters:

url - the url that will be serviced by this Engine

body - the JSON body to POST which will be stringified first

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbPostAction

put

public Response put(java.lang.String url,
                    JSNode body)

Convenience overloading of #service(Request, Response) to run a REST PUT Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Successful PUTs that update an existing resource should return a 204. If the PUT references a resource that does not exist, a 404 will be returned.

Parameters:

url - the url that will be serviced by this Engine

body - the JSON body to POST which will be stringified first

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbPutAction

patch

public Response patch(java.lang.String url,
                      JSNode body)

Convenience overloading of #service(Request, Response) to run a REST PATCH Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Successful PATCHes that update an existing resource should return a 204. If the PATCH references a resource that does not exist, a 404 will be returned.

Parameters:

url - the url for a specific resource that should be PATCHed that will be serviced by this Engine

body - the JSON body to POST which will be stringified first

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response), DbPatchAction

delete

public Response delete(java.lang.String url)

Convenience overloading of #service(Request, Response) to run a REST DELETE Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Parameters:

url - the url of the resource to be DELETED

Returns:

the Response generated by handling the Request with status 204 if the delete was successful or 404 if the resource was not found

See Also:

service(Request, Response), DbDeleteAction

delete

public Response delete(java.lang.String url,
                       JSArray hrefs)

Convenience overloading of #service(Request, Response) to run a REST DELETE Request on this Engine.

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Parameters:

url - the url of the resource to be DELETED

hrefs - the hrefs of the resource to delete

Returns:

the Response generated by handling the Request with status 204 if the delete was successful or 404 if the resource was not found

See Also:

service(Request, Response), DbDeleteAction

service

public Response service(java.lang.String method,
                        java.lang.String url)

Convenience overloading of #service(Request, Response)

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Parameters:

method - the http method of the requested operation

url - the url that will be serviced by this Engine

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response)

service

public Response service(java.lang.String method,
                        java.lang.String url,
                        java.lang.String body)

Convenience overloading of #service(Request, Response)

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Parameters:

method - the http method of the requested operation

url - the url that will be serviced by this Engine.

body - a stringified JSON body presumably to PUT/POST/PATCH

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response)

service

public Response service(java.lang.String method,
                        java.lang.String url,
                        java.lang.String body,
                        java.util.Map<java.lang.String,java.lang.String> params)

Convenience overloading of #service(Request, Response)

IMPORTANT: This method does not make an external HTTP request, it runs the request on this Engine. If you want to make an external HTTP request see RestClient.

Parameters:

method - the http method of the requested operation

url - the url that will be serviced by this Engine.

body - a stringified JSON body presumably to PUT/POST/PATCH

params - additional key/value pairs to add to the url query string

Returns:

the Response generated by handling the Request

See Also:

service(Request, Response)

service

public Chain service(Request req,
                     Response res)

The main entry point for processing a Request and generating Response content.

This method is designed to be called by integrating runtimes such as EngineServlet or by Actions that need to make recursive calls to the Engine when performing composite operations.

The host and port component of the Request url are ignored assuming that this Engine instance is supposed to be servicing the request. The url does not have to start with "http[s]://". If it does not, urls that start with "/" or not are handled the same.

All of the following would be processed the same way:

• https://library.com/v1/library/books?ISBN=1234567890
• https://library.com:8080/v1/library/books?ISBN=1234567890
• https://localhost/v1/library/books?ISBN=1234567890
• /v1/library/books?ISBN=1234567890
• v1/library/books?ISBN=1234567890

Parameters:

req - the api Request

res - the api Response

Returns:

the Chain representing all of the actions executed in populating the Response

isStarted

public boolean isStarted()

withEngineListener

public Engine withEngineListener(Engine.EngineListener listener)

Registers listener to receive Engine, Api, request and error callbacks.

Parameters:

listener - the listener to add

Returns:

this

getApis

public java.util.List<Api> getApis()

getApi

public Api getApi(java.lang.String apiName)

withApi

public Engine withApi(Api api)

startupApi

protected void startupApi(Api api)

removeApi

public void removeApi(Api api)

Removes the api, notifies EngineListeners and calls api.shutdown().

Parameters:

api - the api to be removed

shutdownApi

protected void shutdownApi(Api api)

withAllowHeaders

public Engine withAllowHeaders(java.lang.String allowHeaders)

getLastResponse

public Response getLastResponse()

Returns:

the last response serviced by this Engine.

getResource

public java.net.URL getResource(java.lang.String name)

getConfigPath

public java.lang.String getConfigPath()

withConfigPath

public Engine withConfigPath(java.lang.String configPath)

getConfigProfile

public java.lang.String getConfigProfile()

withConfigProfile

public Engine withConfigProfile(java.lang.String configProfile)