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

Class 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 Detail

      • _httpMethod

        protected org.refcodes.web.HttpMethod _httpMethod

      • _locatorPathPattern

        protected String _locatorPathPattern

      • _locatorRegExp

        protected Pattern _locatorRegExp

      • _connectionStatus

        protected org.refcodes.component.ConnectionStatus _connectionStatus

    • Method Detail

      • 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).

      • 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 aCloseInMillis)
        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

      • 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