Class HttpService

  • All Implemented Interfaces:
    ArService

    public final class HttpService
    extends java.lang.Object
    implements ArService
    A concrete Arrowhead service, exposing its functions as HTTP endpoints.

    Please refer to the package documentation for more details about how this class can be used.

    • Constructor Detail

      • HttpService

        public HttpService()
    • Method Detail

      • name

        public HttpService name​(java.lang.String name)
        Sets name of this service. Must be specified.

        Service names are also referred to as service definitions.

        While any characters may be used in the name, it is recommended to stick to the lowercase alphabetic characters, the numeric characters and dash of the ASCII character set (a-z 0-9 -) to maximize compatibility with existing tools and solutions.

        Parameters:
        name - Desired service name.
        Returns:
        This service.
      • basePath

        public HttpService basePath​(java.lang.String basePath)
        Sets service URI, in this case a base path, that must be matched by HTTP requests received by this service. Must be specified.

        The base path must start with a forward slash (/), must not end with a forward slash, and may only contain the following characters:

             A–Z a–z 0–9 - . _ ~ ! $ & ' ( ) * + , ; / = : @
         
        Percent encodings may not be used. If the given path is the root path, which consists only of a forward slash, the requirement of there being no trailing slash is ignored.

        Note that while RFC 3986 explicitly permits all the above listed characters, it is recommended to stick to the lowercase alphabetic characters, the numeric characters and dash (a-z 0-9 -) to maximize compatibility with existing tools and solutions.

        Parameters:
        basePath - Target base path.
        Returns:
        This service.
        See Also:
        RFC 3986, Section 3.3
      • encodings

        public HttpService encodings​(EncodingDescriptor... encodings)
        Declares what data encodings this service can read and write. Must be specified.

        While this service will prevent messages claimed to be encoded with other encodings from being received, stating that an encoding can be read and written does not itself guarantee it. It is up to the service creator to ensure that such capabilities are indeed available. For most intents and purposes, the most adequate way of achieving this is by using Data Transfer Objects (DTOs), more of which you can read about in the package documentation for the se.arkalix.dto package.

        Parameters:
        encodings - Encodings declared to be supported. At least one must be provided. The first specified encoding is used by default when received requests do not include enough details about their bodies.
        Returns:
        This service.
        See Also:
        Data Transfer Object Utilities
      • metadata

        public HttpService metadata​(java.util.Map<java.lang.String,​java.lang.String> metadata)
        Sets metadata to associate with this service, replacing any previously associated metadata. What significance the data have depend on the service. The data could, for example, be distributed to a service registry and be used to help prospective service consumers determine whether this service is the one they should be using.
        Parameters:
        metadata - Map of metadata.
        Returns:
        This service.
      • metadata

        public HttpService metadata​(java.lang.String key,
                                    java.lang.String value)
        Saves key/value pair into the metadata map associated with this service.
        Parameters:
        key - Desired key.
        value - Desired value.
        Returns:
        This service.
      • version

        public HttpService version​(int version)
        Sets service version.

        If no version is explicitly set, zero will be used by default.

        Parameters:
        version - Service version.
        Returns:
        This service.
      • options

        public HttpService options​(java.lang.String path,
                                   HttpRouteHandler handler)
        Adds incoming HTTP request route to this service, handling OPTIONS requests matching given pattern.
        Parameters:
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        route(HttpRoute), RFC 7231, Section 4.3.7
      • connect

        public HttpService connect​(java.lang.String path,
                                   HttpRouteHandler handler)
        Adds incoming HTTP request route to this service, handling CONNECT requests matching given pattern.
        Parameters:
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        route(HttpRoute), RFC 7231, Section 4.3.6
      • patch

        public HttpService patch​(java.lang.String path,
                                 HttpRouteHandler handler)
        Adds incoming HTTP request route to this service, handling PATCH requests matching given pattern.
        Parameters:
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        route(HttpRoute), RFC 5789
      • route

        public HttpService route​(HttpRoute route)
        Adds incoming HTTP request route to this service.

        A route is a primary handler for a particular set of HTTP requests. If an incoming HTTP request matches its method and path pattern, it is executed with the expectation that it will specify an HTTP response. However, if a filter executed before the route responds to the request or throws an exception, it is never invoked. In the case of either a filter or a route throwing an exception, any registered catcher matching the request and exception will be given a chance to handle the exception.

        Parameters:
        route - HTTP route to add.
        Returns:
        This service.
        See Also:
        GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE
      • route

        public HttpService route​(HttpMethod method,
                                 java.lang.String pattern,
                                 HttpRouteHandler handler)
        Adds incoming HTTP request route to this service.

        A route is a primary handler for a particular set of HTTP requests. If an incoming HTTP request matches its method and path pattern, it is executed with the expectation that it will specify an HTTP response. However, if a filter executed before the route responds to the request or throws an exception, it is never invoked. In the case of either a filter or a route throwing an exception, any registered catcher matching the request and exception will be given a chance to handle the exception.

        Parameters:
        method - Request method to match.
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE
      • route

        public HttpService route​(java.lang.String pattern,
                                 HttpRouteHandler handler)
        Adds incoming HTTP request route to this service.

        A route is a primary handler for a particular set of HTTP requests. If an incoming HTTP request matches its method and path pattern, it is executed with the expectation that it will specify an HTTP response. However, if a filter executed before the route responds to the request or throws an exception, it is never invoked. In the case of either a filter or a route throwing an exception, any registered catcher matching the request and exception will be given a chance to handle the exception.

        This method creates a route that matches any method.

        Parameters:
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE
      • route

        public HttpService route​(HttpMethod method,
                                 HttpRouteHandler handler)
        Adds incoming HTTP request route to this service.

        A route is a primary handler for a particular set of HTTP requests. If an incoming HTTP request matches its method and path pattern, it is executed with the expectation that it will specify an HTTP response. However, if a filter executed before the route responds to the request or throws an exception, it is never invoked. In the case of either a filter or a route throwing an exception, any registered catcher matching the request and exception will be given a chance to handle the exception.

        This method creates a route that matches any path.

        Parameters:
        method - Request method to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE
      • route

        public HttpService route​(HttpRouteHandler handler)
        Adds incoming HTTP request route to this service.

        A route is a primary handler for a particular set of HTTP requests. If an incoming HTTP request matches its method and path pattern, it is executed with the expectation that it will specify an HTTP response. However, if a filter executed before the route responds to the request or throws an exception, it is never invoked. In the case of either a filter or a route throwing an exception, any registered catcher matching the request and exception will be given a chance to handle the exception.

        This method creates a route that matches any method or path.

        Parameters:
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, PATCH, TRACE
      • catcher

        public HttpService catcher​(HttpCatcher<?> catcher)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        If multiple catchers are created with matching methods, path patterns and exception class, the one with the smallest ordinal will be executed first. Execution continues, in order, until each catcher has been given the opportunity to handle the exception.

        Parameters:
        catcher - Exception catcher to add.
        Returns:
        This service.
      • catcher

        public <T extends java.lang.Throwable> HttpService catcher​(HttpMethod method,
                                                                   java.lang.String pattern,
                                                                   java.lang.Class<T> exceptionClass,
                                                                   HttpCatcherHandler<T> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        Parameters:
        method - Request method to match.
        pattern - Request path pattern to match.
        exceptionClass - Exception class to be assignable to.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public HttpService catcher​(HttpMethod method,
                                   java.lang.String pattern,
                                   HttpCatcherHandler<java.lang.Throwable> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any exception.

        Parameters:
        method - Request method to match.
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public HttpService catcher​(java.lang.String pattern,
                                   HttpCatcherHandler<java.lang.Throwable> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any method or exception.

        Parameters:
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public <T extends java.lang.Throwable> HttpService catcher​(java.lang.String pattern,
                                                                   java.lang.Class<T> exceptionClass,
                                                                   HttpCatcherHandler<T> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any method.

        Parameters:
        pattern - Request path pattern to match.
        exceptionClass - Exception class to be assignable to.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public HttpService catcher​(HttpMethod method,
                                   HttpCatcherHandler<java.lang.Throwable> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any path or exception.

        Parameters:
        method - Request method to match.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public <T extends java.lang.Throwable> HttpService catcher​(HttpMethod method,
                                                                   java.lang.Class<T> exceptionClass,
                                                                   HttpCatcherHandler<T> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any path.

        Parameters:
        method - Request method to match.
        exceptionClass - Exception class to be assignable to.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public <T extends java.lang.Throwable> HttpService catcher​(java.lang.Class<T> exceptionClass,
                                                                   HttpCatcherHandler<T> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any method or path.

        Parameters:
        exceptionClass - Exception class to be assignable to.
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • catcher

        public HttpService catcher​(HttpCatcherHandler<java.lang.Throwable> handler)
        Adds an exception catcher to this service.

        An exception catcher is invoked whenever an exception occurs in a filter, route handler, or other catcher, while handling an incoming HTTP request that matches its method, path pattern and exception class.

        This method creates a catcher that matches any method, path or exception.

        Parameters:
        handler - Handler to invoke with matching exceptions.
        Returns:
        This service.
        See Also:
        catcher(HttpCatcher)
      • filter

        public HttpService filter​(HttpFilter filter)
        Adds incoming HTTP request filter to the created service.

        Filters are executed with incoming HTTP requests before they end up at their designated routes. Each filter matching the method and path of the request is given the opportunity read the request, modify its headers and, potentially, respond to the request. If a response is generated, no more handler are invoked with the request, unless sending the response fails and a catcher is executed.

        If multiple filters are created with matching methods or path patterns, the one with the smallest ordinal will be executed first. If no filter responds to the request, all matching filters are executed before the request is provided to its designated route.

        Parameters:
        filter - HTTP request filter to add.
        Returns:
        This service.
      • filter

        public HttpService filter​(HttpMethod method,
                                  java.lang.String pattern,
                                  HttpFilterHandler handler)
        Adds incoming HTTP request filter to the created service.

        Filters are executed with incoming HTTP requests before they end up at their designated routes. Each filter matching the method and path of the request is given the opportunity read the request, modify its headers and, potentially, respond to the request. If a response is generated, no more handler are invoked with the request, unless sending the response fails and a catcher is executed.

        Parameters:
        method - Request method to match.
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        filter(HttpFilter)
      • filter

        public HttpService filter​(java.lang.String pattern,
                                  HttpFilterHandler handler)
        Adds incoming HTTP request filter to the created service.

        Filters are executed with incoming HTTP requests before they end up at their designated routes. Each filter matching the method and path of the request is given the opportunity read the request, modify its headers and, potentially, respond to the request. If a response is generated, no more handler are invoked with the request, unless sending the response fails and a catcher is executed.

        This method creates a filter that matches any method.

        Parameters:
        pattern - Request path pattern to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        filter(HttpFilter)
      • filter

        public HttpService filter​(HttpMethod method,
                                  HttpFilterHandler handler)
        Adds incoming HTTP request filter to the created service.

        Filters are executed with incoming HTTP requests before they end up at their designated routes. Each filter matching the method and path of the request is given the opportunity read the request, modify its headers and, potentially, respond to the request. If a response is generated, no more handler are invoked with the request, unless sending the response fails and a catcher is executed.

        This method creates a filter that matches any path.

        Parameters:
        method - Request method to match.
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        filter(HttpFilter)
      • filter

        public HttpService filter​(HttpFilterHandler handler)
        Adds incoming HTTP request filter to the created service.

        Filters are executed with incoming HTTP requests before they end up at their designated routes. Each filter matching the method and path of the request is given the opportunity read the request, modify its headers and, potentially, respond to the request. If a response is generated, no more handler are invoked with the request, unless sending the response fails and a catcher is executed.

        This method creates a filter that matches any method or path.

        Parameters:
        handler - Handler to invoke with matching requests.
        Returns:
        This service.
        See Also:
        filter(HttpFilter)
      • name

        public java.lang.String name()
        Gets service name.
        Specified by:
        name in interface ArService
        Returns:
        Service name.
        See Also:
        name(String)
      • basePath

        public java.lang.String basePath()
        Returns:
        Currently set base path, or an empty string if none has been set.
        See Also:
        basePath(String)
      • uri

        public java.lang.String uri()
        Gets service URI.
        Specified by:
        uri in interface ArService
        Returns:
        Service URI.
        See Also:
        basePath(String)
      • transport

        public TransportDescriptor transport()
        Description copied from interface: ArService
        Gets descriptor for application-level transport protocol through which service is made available to other systems.
        Specified by:
        transport in interface ArService
        Returns:
        Service transport descriptor.
      • metadata

        public java.util.Map<java.lang.String,​java.lang.String> metadata()
        Gets service metadata.
        Specified by:
        metadata in interface ArService
        Returns:
        Unmodifiable map of service metadata.
        See Also:
        metadata(Map)
      • version

        public int version()
        Description copied from interface: ArService
        Gets service version.
        Specified by:
        version in interface ArService
        Returns:
        Currently set service version.
        See Also:
        version(int)