Package io.inversion

Class Engine

java.lang.Object
io.inversion.Rule<Engine>
io.inversion.Engine
All Implemented Interfaces:
Comparable<Engine>
public class Engine extends Rule<Engine>
Matches inbound Request Url paths to an Api Endpoint and executes associated Actions.

  • Field Details

    • listeners

      protected final transient 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 List<Api> apis
      The Apis being service by this Engine

    • corsAllowHeaders

      protected 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 String configPath
      Optional override for the configPath sys/env prop used by Config to locate configuration property files
      See Also:

    • configProfile

      protected String configProfile
      Optional override for the sys/env prop used by Config to determine which profile specific configuration property files to load
      See Also:

  • Constructor Details

    • Engine

      public Engine()

    • Engine

      public Engine(Api... apis)

  • Method Details

    • 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(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:

    • get

      public Response get(String url, Map<String,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:

    • get

      public Response get(String url, 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:

    • post

      public Response post(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:

    • put

      public Response put(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:

    • patch

      public Response patch(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:

    • delete

      public Response delete(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:

    • delete

      public Response delete(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

      public Response service(String method, 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

      public Response service(String method, String url, 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

      public Response service(String method, String url, String body, Map<String,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

      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 List<Api> getApis()

    • getApi

      public Api getApi(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(String allowHeaders)

    • getLastResponse

      public Response getLastResponse()
      Returns:
      the last response serviced by this Engine.

    • getResource

      public URL getResource(String name)

    • getConfigPath

      public String getConfigPath()

    • withConfigPath

      public Engine withConfigPath(String configPath)

    • getConfigProfile

      public String getConfigProfile()

    • withConfigProfile

      public Engine withConfigProfile(String configProfile)