Module org.refcodes.rest
Package org.refcodes.rest

Class RestEndpointBuilder

java.lang.Object
org.refcodes.rest.RestEndpointBuilder
All Implemented Interfaces:
org.refcodes.component.Closable, org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>, org.refcodes.component.ConnectionStatusAccessor, org.refcodes.component.LinkComponent, org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>, org.refcodes.component.Openable, org.refcodes.component.Openable.OpenBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>, org.refcodes.component.OpenedAccessor, RestEndpoint, RestRequestConsumer, org.refcodes.web.HttpMethodAccessor, org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestEndpointBuilder>, org.refcodes.web.HttpMethodAccessor.HttpMethodMutator, org.refcodes.web.HttpMethodAccessor.HttpMethodProperty
public class RestEndpointBuilder extends Object implements RestEndpoint, org.refcodes.web.HttpMethodAccessor.HttpMethodProperty, org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestEndpointBuilder>, org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>, org.refcodes.component.ConnectionStatusAccessor
An RestEndpointBuilder extends an RestEndpoint with builder functionality and adds lambda support for handling the requests addressed to this RestEndpoint. The lambda defined as RestRequestConsumer acts as the single listener to this RestEndpoint responsible for handling the requests for which this RestEndpoint is responsible. The locator for which an RestEndpointBuilder is responsible for is defined by the RestEndpointBuilder's Locator-Pattern: A single asterisk ("*") matches zero or more characters within a locator name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a locator name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcard: You get an array with the substitutes of the wildcards using the method RestRequestEvent.getWildcardReplacements() . You may name a wildcard by prefixing it with "${someWildcardName}". For example a named wildcard may look as follows: "${arg1}=*" or "${arg2}=**" or "${arg3}=?". You can get the text substituting a named wildcard using the method RestRequestEvent.getWildcardReplacement(String). For ease of use, a named wildcard with single asterisk ("*") such as "${arg1}=*" can be abbreviated as "${arg1}".

  • Field Details

    • _requestObserver

      protected RestRequestConsumer _requestObserver

    • _httpMethod

      protected org.refcodes.web.HttpMethod _httpMethod

    • _locatorPathPattern

      protected String _locatorPathPattern

    • _locatorRegExp

      protected Pattern _locatorRegExp

    • _connectionStatus

      protected org.refcodes.component.ConnectionStatus _connectionStatus

  • Constructor Details

  • Method Details

    • withHttpMethod

      public RestEndpointBuilder withHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
      Specified by:
      withHttpMethod in interface org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestEndpointBuilder>

    • withLocatorPathPattern

      public RestEndpointBuilder withLocatorPathPattern(String aLocatorPathPattern)
      Sets the resource locator pattern as of the Builder-Pattern. The locator may contain wildcards as known from file-systems as follows: A single asterisk ("*") matches zero or more characters within a locator name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a locator name. You may name a wildcard by prefixing it with "${someWildcardName}". For example a named wildcard may look as follows: "${arg1}=*" or "${arg2}=**" or "${arg3}=?". You can get the text substituting a named wildcard using the method RestRequestEvent.getWildcardReplacement(String). For ease of use, a named wildcard with single asterisk ("*") such as "${arg1}=*" can be abbreviated as "${arg1}".
      Parameters:
      aLocatorPathPattern - the locator pattern
      Returns:
      The RestEndpoint builder to continue configuration (as of the Builder-Pattern).

    • withLocatorRegExp

      public RestEndpointBuilder withLocatorRegExp(Pattern aLocatorRegExp)
      Sets the resource locator (regular expression) pattern as of the Builder-Pattern.
      Parameters:
      aLocatorRegExp - the locator (regular expression) pattern
      Returns:
      The RestEndpoint builder to continue configuration (as of the Builder-Pattern).

    • withRequestObserver

      public RestEndpointBuilder withRequestObserver(RestRequestConsumer aLambda)
      Builder method for setting the RestRequestConsumer.
      Parameters:
      aLambda - The (user defined) RestRequestConsumer to handle requests, feel free to code it as lambda expression
      Returns:
      The RestEndpointBuilder for the sake of a fluent API.

    • withOpen

      public RestEndpointBuilder withOpen() throws IOException
      Specified by:
      withOpen in interface org.refcodes.component.Openable.OpenBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>
      Throws:
      IOException

    • withClose

      public RestEndpointBuilder withClose() throws IOException
      Specified by:
      withClose in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>
      Throws:
      IOException

    • withCloseQuietly

      public RestEndpointBuilder withCloseQuietly()
      Specified by:
      withCloseQuietly in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>

    • withCloseIn

      public RestEndpointBuilder withCloseIn(int aCloseMillis)
      Specified by:
      withCloseIn in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestEndpointBuilder>>

    • setLocatorPathPattern

      public void setLocatorPathPattern(String aLocatorPathPattern)
      Sets the resource locator pattern. The locator may contain wildcards as known from file-systems as follows: A single asterisk ("*") matches zero or more characters within a locator name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a locator name. You may name a wildcard by prefixing it with "${someWildcardName}". For example a named wildcard may look as follows: "${arg1}=*" or "${arg2}=**" or "${arg3}=?". You can get the text substituting a named wildcard using the method RestRequestEvent.getWildcardReplacement(String). For ease of use, a named wildcard with single asterisk ("*") such as "${arg1}=*" can be abbreviated as "${arg1}".
      Parameters:
      aLocatorPathPattern - the new locator pattern

    • setLocatorRegExp

      public void setLocatorRegExp(Pattern aLocatorRegExp)
      Sets the resource locator (regular expression) pattern.
      Parameters:
      aLocatorRegExp - the new locator (regular expression) pattern

    • setHttpMethod

      public void setHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
      Specified by:
      setHttpMethod in interface org.refcodes.web.HttpMethodAccessor.HttpMethodMutator

    • setRequestObserver

      public void setRequestObserver(RestRequestConsumer aLambda)
      Sets the RestRequestConsumer to which any requests are delegated upon invocation of the onRequest(RestRequestEvent, org.refcodes.web.HttpServerResponse) method.
      Parameters:
      aLambda - The (user defined) RestRequestConsumer to handle requests, feel free to code it as lambda expression!

    • getRequestObserver

      public RestRequestConsumer getRequestObserver()
      Retrieves the RestRequestConsumer to which any requests are delegated upon invocation of the onRequest(RestRequestEvent, org.refcodes.web.HttpServerResponse) method.
      Returns:
      The (user defined) RestRequestConsumer to handle requests.

    • onRequest

      public void onRequest(RestRequestEvent aRequest, org.refcodes.web.HttpServerResponse aResponse) throws org.refcodes.web.HttpStatusException
      The invoker provides a request context being a RestRequestEvent) describing the request and a response being a HttpServerResponse to be processed upon by your lambda's code. The method works synchronously and waits (blocks the caller's thread) till it finishes execution.
      Specified by:
      onRequest in interface RestRequestConsumer
      Parameters:
      aRequest - The request of type RestRequestEvent describing the request context. Use HttpServerRequest.getRequest(Class) to retrieve the caller's request body or AbstractHttpRequest.getHeaderFields() to retrieve the request's cookies and other Header-Fields.
      aResponse - The response of type HttpServerResponse do be processed upon by the method's implementation. Use HttpServerResponse.setResponse(Object) to provide a response for the client. Use AbstractHttpResponse.getHeaderFields() to set cookies or modify Header-Fields. Throw one of the HttpStatusException sub-types to signal an according erroneous HTTP state.
      Throws:
      org.refcodes.web.HttpStatusException - to be thrown in case something went wrong.

    • getHttpMethod

      public org.refcodes.web.HttpMethod getHttpMethod()
      Specified by:
      getHttpMethod in interface org.refcodes.web.HttpMethodAccessor

    • getLocatorPathPattern

      public String getLocatorPathPattern()
      Retrieves the resource Locator-Pattern this endpoint has been registered to. The Locator-Pattern may contain wildcards as known from file-systems as follows: A single asterisk ("*") matches zero or more characters within a locator name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a locator name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcard: You get an array with the substitutes of the wildcards using the RestRequestEvent's method RestRequestEvent.getWildcardReplacements() inside the RestRequestConsumer.onRequest(RestRequestEvent, org.refcodes.web.HttpServerResponse) method. You may name a wildcard by prefixing it with "{someWildcardName}". For example a named wildcard may look as follows: "{arg1}*" or "{arg2}**" or "{arg3}?". The RestRequestEvent lets you access the wildcard substitutes either by index or by name.
      Specified by:
      getLocatorPathPattern in interface RestEndpoint

    • getLocatorRegExp

      public Pattern getLocatorRegExp()
      Retrieves the resource locator (regular expression) pattern this endpoint has been registered to. The RestRequestEvent lets you access the matching regular expression groups either by index or by name.
      Specified by:
      getLocatorRegExp in interface RestEndpoint

    • open

      public void open() throws IOException
      Specified by:
      open in interface org.refcodes.component.Openable
      Throws:
      IOException

    • close

      public void close() throws IOException
      Specified by:
      close in interface org.refcodes.component.Closable
      Throws:
      IOException

    • getConnectionStatus

      public org.refcodes.component.ConnectionStatus getConnectionStatus()
      Specified by:
      getConnectionStatus in interface org.refcodes.component.ConnectionStatusAccessor