Package io.muserver.rest

Class RestHandlerBuilder

    • Constructor Detail

      • RestHandlerBuilder

        public RestHandlerBuilder()

    • Method Detail

      • addResource

        public RestHandlerBuilder addResource​(java.lang.Object... resources)
        Adds one or more rest resources to this handler
        Parameters:
        resources - One or more instances of classes that are decorated with Path annotations.
        Returns:
        This builder

      • addCustomWriter

        public <T> RestHandlerBuilder addCustomWriter​(jakarta.ws.rs.ext.MessageBodyWriter<T> writer)

        Registers an object that can write custom classes to responses.

        For example, if you return an instance of MyClass from a REST method, you need to specify how that gets serialised with a MessageBodyWriter<MyClass> writer.

        Type Parameters:
        T - The type of object that the writer can serialise
        Parameters:
        writer - A response body writer
        Returns:
        This builder

      • addCustomReader

        public <T> RestHandlerBuilder addCustomReader​(jakarta.ws.rs.ext.MessageBodyReader<T> reader)

        Registers an object that can deserialise request bodies into custom classes.

        For example, if you specify that the request body is a MyClass, you need to specify how that gets deserialised with a MessageBodyReader<MyClass> reader.

        Type Parameters:
        T - The type of object that the reader can deserialise
        Parameters:
        reader - A request body reader
        Returns:
        This builder

      • addCustomParamConverterProvider

        public RestHandlerBuilder addCustomParamConverterProvider​(jakarta.ws.rs.ext.ParamConverterProvider paramConverterProvider)

        Registers an object that can convert rest method parameters (e.g. querystring, header, form or path params) into custom classes.

        In most cases, it is easier to instead use addCustomParamConverter(Class, ParamConverter)

        Parameters:
        paramConverterProvider - A provider of parameter converters
        Returns:
        This builder

      • addCustomParamConverter

        public <P> RestHandlerBuilder addCustomParamConverter​(java.lang.Class<P> paramClass,
                                                      jakarta.ws.rs.ext.ParamConverter<P> converter)

        Registers a parameter converter class that convert strings to and from a custom class.

        This allows you to specify query string parameters, form values, header params and path params as custom classes.

        For more functionality, addCustomParamConverterProvider(ParamConverterProvider) is also available.

        Type Parameters:
        P - The type of the parameter
        Parameters:
        paramClass - The class that this converter is meant for.
        converter - The converter
        Returns:
        This builder

      • withOpenApiJsonUrl

        public RestHandlerBuilder withOpenApiJsonUrl​(java.lang.String url)
        Enables an Open API JSON URL at the specified endpoint. This JSON describes the API exposed by the rest resources declared by this builder, and can be used by UIs such as Swagger.
        Parameters:
        url - The URL to serve from, for example /openapi.json or null to disable the JSON endpoint. Disabled by default.
        Returns:
        The current Rest Handler Builder
        See Also:
        withOpenApiDocument(OpenAPIObjectBuilder), withOpenApiHtmlUrl(String)

      • withCollectionParameterStrategy

        public RestHandlerBuilder withCollectionParameterStrategy​(CollectionParameterStrategy collectionParameterStrategy)
        Specifies if values passed to method parameters with QueryParam or HeaderParam annotations should be transformed or not.

        The primary use of this is to allow querystring parameters such as /path?value=one,two,three to be interpreted as a list of three values rather than a single string. This only applies to parameters that are collections.

        The default is CollectionParameterStrategy.NO_TRANSFORM which is the JAX-RS standard.

        Note: until MuServer 1.0, if no value is specified but methods with collection parameters are detected then the handler will fail to start and this value will need to be explicitly set. This is in order to highlight the change in behaviour introduced in Mu Server 0.70 where it used CollectionParameterStrategy.SPLIT_ON_COMMA behaviour.

        Parameters:
        collectionParameterStrategy - The strategy to use
        Returns:
        This builder

      • withOpenApiHtmlCss

        public RestHandlerBuilder withOpenApiHtmlCss​(java.lang.String css)
        When using the HTML endpoint made available by calling withOpenApiDocument(OpenAPIObjectBuilder) this allows you to override the default CSS that is used.
        Parameters:
        css - A string containing a style sheet definition.
        Returns:
        The current Rest Handler Builder

      • withOpenApiDocument

        public RestHandlerBuilder withOpenApiDocument​(OpenAPIObjectBuilder openAPIObject)

        Use this value to create JSON and HTML documentation for your rest service.

        Minimal example:

        
     OpenAPIObjectBuilder.openAPIObject()
             .withInfo(InfoObjectBuilder.infoObject()
                 .withTitle("Mu Server Sample API")
                 .withVersion("1.0")
                 .build())

        Extended example:

        
     OpenAPIObjectBuilder.openAPIObject()
             .withInfo(InfoObjectBuilder.infoObject()
                 .withTitle("Mu Server Sample API")
                 .withVersion("1.0")
                 .withLicense(LicenseObjectBuilder.Apache2_0())
                 .withDescription("This is the **description**\n\nWhich is markdown")
                 .withTermsOfService(URI.create("http://example.org/terms/"))
                 .build())
             .withExternalDocs(externalDocumentationObject()
                 .withDescription("Full documentation")
                 .withUrl(URI.create("http://example.org/docs"))
                 .build())

        The path information and operation information will be automatically generated. By default, you can access the Open API specification of your rest service at /openapi.json or view the HTML at /api.html

        Parameters:
        openAPIObject - An API Object builder with the OpenAPIObjectBuilder.withInfo(InfoObject) set.
        Returns:
        The current Rest Handler Builder
        See Also:
        OpenAPIObjectBuilder.openAPIObject(), withOpenApiJsonUrl(String), withOpenApiHtmlUrl(String)

      • addExceptionMapper

        public <T extends java.lang.Throwable> RestHandlerBuilder addExceptionMapper​(java.lang.Class<T> exceptionClass,
                                                                             jakarta.ws.rs.ext.ExceptionMapper<T> exceptionMapper)

        Adds a mapper that converts an exception to a response.

        For example, you may create a custom exception such as a ValidationException that you throw from your jax-rs methods. A mapper for this exception type could return a Response with a 400 code and a custom validation error message.

        Type Parameters:
        T - The exception type that the mapper can handle
        Parameters:
        exceptionClass - The type of exception to map.
        exceptionMapper - A function that creates a Response suitable for the exception.
        Returns:
        Returns this builder.

      • restHandler

        public static RestHandlerBuilder restHandler​(java.lang.Object... resources)

        Creates a handler builder for JAX-RS REST services.

        Note that CORS is disabled by default.

        Parameters:
        resources - Instances of classes that have a Path annotation.
        Returns:
        Returns a builder that can be used to specify more config

      • addRequestFilter

        public RestHandlerBuilder addRequestFilter​(jakarta.ws.rs.container.ContainerRequestFilter filter)

        Registers a request filter, which is run before a rest method is executed.

        It will be run after the method has been matched, or if the PreMatching annotation is applied to the filter then it will run before matching occurs.

        To access the ResourceInfo or MuRequest for the current request, the following code can be used:

        
 ResourceInfo resourceInfo = (ResourceInfo) context.getProperty(MuRuntimeDelegate.RESOURCE_INFO_PROPERTY);
 MuRequest muRequest = (MuRequest) context.getProperty(MuRuntimeDelegate.MU_REQUEST_PROPERTY);
        Parameters:
        filter - The filter to register
        Returns:
        This builder

      • addResponseFilter

        public RestHandlerBuilder addResponseFilter​(jakarta.ws.rs.container.ContainerResponseFilter filter)
        Registers a response filter, which is called after execution of a method takes place.

        To access the ResourceInfo or MuRequest for the current request, the following code can be used:

        
 ResourceInfo resourceInfo = (ResourceInfo) context.getProperty(MuRuntimeDelegate.RESOURCE_INFO_PROPERTY);
 MuRequest muRequest = (MuRequest) context.getProperty(MuRuntimeDelegate.MU_REQUEST_PROPERTY);
        Parameters:
        filter - The filter to register
        Returns:
        This builder

      • addCustomSchema

        public RestHandlerBuilder addCustomSchema​(java.lang.Class<?> dataClass,
                                          SchemaObject schema)
        Registers a custom OpenAPI schema description for the given class.

        This allows you to provide rich schema objects (created with SchemaObjectBuilder.schemaObject()) in your OpenAPI documents. Wherever the give type is used as a parameter or body, the given schema will be used to describe it.

        Warning: When generating OpenAPI documentation, the schema information will be added to the /components/schemas section with a key equal to the simple class name of the given data class. If you do not wish to expose the class name in your API documentation, you can override it by annotating the class with a Description annotation in which case the value field will be used.

        Parameters:
        dataClass - The type of class to describe
        schema - The schema object describing the class
        Returns:
        This builder

      • addWriterInterceptor

        public RestHandlerBuilder addWriterInterceptor​(jakarta.ws.rs.ext.WriterInterceptor writerInterceptor)
        Registers a writer interceptor allowing for inspection and alteration of response bodies.

        Interceptors are executed in the order added, and are called before any message body writers added by addCustomWriter(MessageBodyWriter).

        To access the ResourceInfo or MuRequest for the current request, the following code can be used:

        
 ResourceInfo resourceInfo = (ResourceInfo) context.getProperty(MuRuntimeDelegate.RESOURCE_INFO_PROPERTY);
 MuRequest muRequest = (MuRequest) context.getProperty(MuRuntimeDelegate.MU_REQUEST_PROPERTY);
        Parameters:
        writerInterceptor - The interceptor to add. If null then this is a no-op.
        Returns:
        This builder

      • addReaderInterceptor

        public RestHandlerBuilder addReaderInterceptor​(jakarta.ws.rs.ext.ReaderInterceptor readerInterceptor)
        Registers a reader interceptor allowing for inspection and alteration of request bodies.

        Interceptors are executed in the order added, and are called before any message body readers added by addCustomReader(MessageBodyReader).

        To access the ResourceInfo or MuRequest for the current request, the following code can be used:

        
 ResourceInfo resourceInfo = (ResourceInfo) context.getProperty(MuRuntimeDelegate.RESOURCE_INFO_PROPERTY);
 MuRequest muRequest = (MuRequest) context.getProperty(MuRuntimeDelegate.MU_REQUEST_PROPERTY);
        Parameters:
        readerInterceptor - The interceptor to add. If null then this is a no-op.
        Returns:
        This builder

      • resources

        public java.util.List<java.lang.Object> resources()
        Returns:
        The current value of this property

      • customWriters

        public java.util.List<jakarta.ws.rs.ext.MessageBodyWriter<?>> customWriters()
        Returns:
        The current value of this property

      • writerInterceptors

        public java.util.List<jakarta.ws.rs.ext.WriterInterceptor> writerInterceptors()
        Returns:
        The current value of this property

      • customReaders

        public java.util.List<jakarta.ws.rs.ext.MessageBodyReader<?>> customReaders()
        Returns:
        The current value of this property

      • readerInterceptors

        public java.util.List<jakarta.ws.rs.ext.ReaderInterceptor> readerInterceptors()
        Returns:
        The current value of this property

      • customParamConverterProviders

        public java.util.List<jakarta.ws.rs.ext.ParamConverterProvider> customParamConverterProviders()
        Returns:
        The current value of this property

      • customSchemas

        public java.util.Map<java.lang.Class<?>,​SchemaObject> customSchemas()
        Returns:
        The current value of this property

      • openApiJsonUrl

        public java.lang.String openApiJsonUrl()
        Returns:
        The current value of this property

      • openApiHtmlUrl

        public java.lang.String openApiHtmlUrl()
        Returns:
        The current value of this property

      • openAPIObject

        public OpenAPIObjectBuilder openAPIObject()
        Returns:
        The current value of this property

      • openApiHtmlCss

        public java.lang.String openApiHtmlCss()
        Returns:
        The current value of this property

      • exceptionMappers

        public java.util.Map<java.lang.Class<? extends java.lang.Throwable>,​jakarta.ws.rs.ext.ExceptionMapper<? extends java.lang.Throwable>> exceptionMappers()
        Returns:
        The current value of this property

      • preMatchRequestFilters

        public java.util.List<jakarta.ws.rs.container.ContainerRequestFilter> preMatchRequestFilters()
        Returns:
        The current value of this property

      • requestFilters

        public java.util.List<jakarta.ws.rs.container.ContainerRequestFilter> requestFilters()
        Returns:
        The current value of this property

      • responseFilters

        public java.util.List<jakarta.ws.rs.container.ContainerResponseFilter> responseFilters()
        Returns:
        The current value of this property

      • corsConfig

        public CORSConfig corsConfig()
        Returns:
        The current value of this property

      • schemaObjectCustomizers

        public java.util.List<SchemaObjectCustomizer> schemaObjectCustomizers()
        Returns:
        The current value of this property

      • collectionParameterStrategy

        public CollectionParameterStrategy collectionParameterStrategy()
        Returns:
        The current value of this property