io microsphere spring web metadata WebEndpointMapping

WebEndpointMapping

Type: Class | Module: microsphere-spring-web | Package: io.microsphere.spring.web.metadata | Since: 1.0.0

Source: microsphere-spring-web/src/main/java/io/microsphere/spring/web/metadata/WebEndpointMapping.java

Overview

The meta-data class for Web Endpoint Mapping that could be one of these endpoints:

- `jakarta.servlet.Servlet Servlet`
- `jakarta.servlet.Filter Servlet's Filter`
- Spring WebMVC `org.springframework.web.servlet.DispatcherServlet DispatcherServlet`
- Spring WebFlux `org.springframework.web.reactive.DispatcherHandler DispatcherHandler`
- Customized

The method #getKind() can be used to identify the kind of endpoints, and the method #getEndpoint() is an abstract presentation of actual endpoint that may be :

- `jakarta.servlet.ServletRegistration#getName() the name of Servlet`
- `jakarta.servlet.FilterRegistration#getName() the name of Servlet's Filter`
- the any handler of Spring WebMVC `org.springframework.web.servlet.HandlerMapping`:
 
     - The `String` presenting the name of Handler bean
     - The `org.springframework.web.servlet.mvc.Controller` Bean
     - The `HandlerMethod` could be annotated the `RequestMapping @RequestMapping`
     - The `org.springframework.web.servlet.function.HandlerFunction` since Spring Framework 5.2
 

- the any handler of Spring WebFlux `org.springframework.web.reactive.HandlerMapping`:
 
     - The `String` presenting the name of Handler bean
     - The `HandlerMethod` could be annotated the `RequestMapping @RequestMapping`
     - The `org.springframework.web.reactive.function.server.RouterFunction` since Spring Framework 5.0

The method #getSource() can trace the source of WebEndpointMapping if present, it could be :

- `jakarta.servlet.ServletContext ServletContext`
- Spring WebMVC `org.springframework.web.servlet.HandlerMapping`
- Spring WebFlux `org.springframework.web.reactive.HandlerMapping`

, or it's #UNKNOWN_SOURCE non-source

Declaration

public class WebEndpointMapping<E>

Author: Mercy

Version Information

• Introduced in: 1.0.0
• Current Project Version: 0.2.27-SNAPSHOT

Version Compatibility

This component is tested and compatible with the following Java versions:

Java Version	Status
Java 17	✅ Compatible
Java 21	✅ Compatible
Java 25	✅ Compatible

Examples

Method Examples

endpoint

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.endpoint("myServlet");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.endpoint(handlerMethod);

pattern

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.pattern("/api/users");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.pattern("/api/products/{id}");

patterns

// For a Servlet endpoint with a list of pattern strings
List<String> patternList = Arrays.asList("/api/users", "/api/orders");
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.patterns(patternList, Function.identity());

// For a WebFlux endpoint with custom objects that have a getName() method
List<MyPathPattern> patterns = getCustomPatternObjects();
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns(patterns, MyPathPattern::getName);

patterns

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.patterns("/api/users", "/api/orders");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns("/api/products/{id}", "/api/categories/{categoryId}");

patterns

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.patterns(Arrays.asList("/api/users", "/api/orders"));

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns(Arrays.asList("/api/products/{id}", "/api/categories/{categoryId}"));

method

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.method(HttpMethod.GET);

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.method(HttpMethod.POST);

method

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.method("GET");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.method("POST");

methods

// For a Servlet endpoint with a list of HttpMethod enums
List<HttpMethod> methodList = Arrays.asList(HttpMethod.GET, HttpMethod.POST);
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.methods(methodList, HttpMethod::name);

// For a WebFlux endpoint with custom objects that have a getMethodName() method
List<MyHttpMethod> methods = getCustomMethodObjects();
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods(methods, MyHttpMethod::getMethodName);

methods

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.methods(HttpMethod.GET, HttpMethod.POST);

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods(HttpMethod.PUT, HttpMethod.DELETE);

methods

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.methods("GET", "POST");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods("PUT", "DELETE");

methods

List<String> methodList = Arrays.asList("GET", "POST");
  WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet();
  builder.endpoint("myServlet").patterns("/api").methods(methodList);

param

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.param("version", "v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.param("userId", 12345);

param

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.param("version=v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.param("userId=12345");

params

// For a Servlet endpoint with a list of parameter objects
List<MyParam> paramList = Arrays.asList(new MyParam("version", "v1"), new MyParam("lang", "en"));
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.params(paramList, p -> p.getName() + "=" + p.getValue());

// For a WebFlux endpoint with custom objects that have a toString() method
List<MyQueryParam> queryParams = getCustomParamObjects();
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.params(queryParams, MyQueryParam::toString);

params

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.params("version=v1", "lang=en");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.params("userId=12345", "active=true");

header

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.header("X-API-Version", "v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.header("Authorization", "Bearer token");

header

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.header("X-API-Version:v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.header("Authorization:Bearer token");

headers

// For a Servlet endpoint with a list of header objects
List<MyHeader> headerList = Arrays.asList(new MyHeader("X-API-Version", "v1"), new MyHeader("Accept-Language", "en"));
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.headers(headerList, h -> h.getName() + ":" + h.getValue());

// For a WebFlux endpoint with custom objects that have a toString() method
List<MyRequestHeader> requestHeaders = getCustomHeaderObjects();
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.headers(requestHeaders, MyRequestHeader::toString);

headers

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.headers("X-API-Version:v1", "Accept-Language:en");

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.headers("Authorization:Bearer token", "X-Request-ID:12345");

consume

// For a Servlet endpoint
WebEndpointMapping.Builder<String> builder = WebEndpointMapping.servlet("myServlet");
builder.consume(MediaType.APPLICATION_JSON);

// For a WebFlux endpoint
WebEndpointMapping.Builder<HandlerMethod> webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.consume(MediaType.TEXT_PLAIN);

Usage

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-spring-web</artifactId>
    <version>${microsphere-spring.version}</version>
</dependency>

Tip: Use the BOM (microsphere-spring-dependencies) for consistent version management. See the Getting Started guide.

Import

import io.microsphere.spring.web.metadata.WebEndpointMapping;

API Reference

Public Methods

Method	Description
endpoint	The HTTP header name for WebEndpointMapping#getId()
pattern	Add a single path pattern to the endpoint mapping.
patterns	Set multiple path patterns to the endpoint mapping from a collection of values.
patterns	Set multiple path patterns to the endpoint mapping.
patterns	Set multiple path patterns to the endpoint mapping.
method	Add a single HTTP method to the endpoint mapping.
method	Add a single HTTP method to the endpoint mapping.
methods	Set multiple HTTP methods to the endpoint mapping from a collection of values.
methods	Set multiple HTTP methods to the endpoint mapping.
methods	Set multiple HTTP methods to the endpoint mapping.
methods	Set multiple HTTP methods to the endpoint mapping from a collection of strings.
param	Add a single request parameter to the endpoint mapping.
param	Add a single request parameter to the endpoint mapping.
params	Set multiple request parameters to the endpoint mapping from a collection of values.
params	Set multiple request parameters to the endpoint mapping.
header	Add a single request header to the endpoint mapping.
header	Add a single request header to the endpoint mapping.
headers	Set multiple request headers to the endpoint mapping from a collection of values.
headers	Set multiple request headers to the endpoint mapping.
consume	Add a single media type to the endpoint mapping that it can consume.

Method Details

endpoint

public Builder<E> endpoint(@Nonnull E endpoint)

The HTTP header name for WebEndpointMapping#getId() / public static final String ID_HEADER_NAME = "microsphere_wem_id";

/** The source is unknown / public static final Object UNKNOWN_SOURCE = new Object();

pattern

public Builder<E> pattern(@Nonnull String pattern)

Add a single path pattern to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.pattern("/api/users");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.pattern("/api/products/{id`");
}

patterns

public <V> Builder<E> patterns(Collection<V> values, Function<V, String> stringFunction)

Set multiple path patterns to the endpoint mapping from a collection of values.

Example Usage

`// For a Servlet endpoint with a list of pattern strings
List patternList = Arrays.asList("/api/users", "/api/orders");
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.patterns(patternList, Function.identity());

// For a WebFlux endpoint with custom objects that have a getName() method
List patterns = getCustomPatternObjects();
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns(patterns, MyPathPattern::getName);
`

patterns

public Builder<E> patterns(@Nonnull String... patterns)

Set multiple path patterns to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.patterns("/api/users", "/api/orders");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns("/api/products/{id`", "/api/categories/{categoryId}");
}

patterns

public Builder<E> patterns(@Nonnull Collection<String> patterns)

Set multiple path patterns to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.patterns(Arrays.asList("/api/users", "/api/orders"));

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.patterns(Arrays.asList("/api/products/{id`", "/api/categories/{categoryId}"));
}

method

public Builder<E> method(@Nonnull HttpMethod method)

Add a single HTTP method to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.method(HttpMethod.GET);

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.method(HttpMethod.POST);
`

method

public Builder<E> method(@Nonnull String method)

Add a single HTTP method to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.method("GET");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.method("POST");
`

methods

public <V> Builder<E> methods(Collection<V> values, Function<V, String> stringFunction)

Set multiple HTTP methods to the endpoint mapping from a collection of values.

Example Usage

`// For a Servlet endpoint with a list of HttpMethod enums
List methodList = Arrays.asList(HttpMethod.GET, HttpMethod.POST);
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.methods(methodList, HttpMethod::name);

// For a WebFlux endpoint with custom objects that have a getMethodName() method
List methods = getCustomMethodObjects();
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods(methods, MyHttpMethod::getMethodName);
`

methods

public Builder<E> methods(@Nonnull HttpMethod... methods)

Set multiple HTTP methods to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.methods(HttpMethod.GET, HttpMethod.POST);

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods(HttpMethod.PUT, HttpMethod.DELETE);
`

methods

public Builder<E> methods(@Nonnull String... methods)

Set multiple HTTP methods to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.methods("GET", "POST");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.methods("PUT", "DELETE");
`

methods

public Builder<E> methods(@Nonnull Collection<String> methods)

Set multiple HTTP methods to the endpoint mapping from a collection of strings.

Example Usage

`List methodList = Arrays.asList("GET", "POST");
  WebEndpointMapping.Builder builder = WebEndpointMapping.servlet();
  builder.endpoint("myServlet").patterns("/api").methods(methodList);
`

param

public Builder<E> param(@Nonnull String name, @Nullable String value)

Add a single request parameter to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.param("version", "v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.param("userId", 12345);
`

param

public Builder<E> param(@Nonnull String nameAndValue)

Add a single request parameter to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.param("version=v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.param("userId=12345");
`

params

public <V> Builder<E> params(Collection<V> values, Function<V, String> stringFunction)

Set multiple request parameters to the endpoint mapping from a collection of values.

Example Usage

`// For a Servlet endpoint with a list of parameter objects
List paramList = Arrays.asList(new MyParam("version", "v1"), new MyParam("lang", "en"));
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.params(paramList, p -> p.getName() + "=" + p.getValue());

// For a WebFlux endpoint with custom objects that have a toString() method
List queryParams = getCustomParamObjects();
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.params(queryParams, MyQueryParam::toString);
`

params

public Builder<E> params(@Nullable String... params)

Set multiple request parameters to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.params("version=v1", "lang=en");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.params("userId=12345", "active=true");
`

header

public <V> Builder<E> header(@Nonnull String name, @Nullable String value)

Add a single request header to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.header("X-API-Version", "v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.header("Authorization", "Bearer token");
`

header

public Builder<E> header(@Nonnull String nameAndValue)

Add a single request header to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.header("X-API-Version:v1");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.header("Authorization:Bearer token");
`

headers

public <V> Builder<E> headers(Collection<V> values, Function<V, String> stringFunction)

Set multiple request headers to the endpoint mapping from a collection of values.

Example Usage

`// For a Servlet endpoint with a list of header objects
List headerList = Arrays.asList(new MyHeader("X-API-Version", "v1"), new MyHeader("Accept-Language", "en"));
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.headers(headerList, h -> h.getName() + ":" + h.getValue());

// For a WebFlux endpoint with custom objects that have a toString() method
List requestHeaders = getCustomHeaderObjects();
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.headers(requestHeaders, MyRequestHeader::toString);
`

headers

public Builder<E> headers(String... headers)

Set multiple request headers to the endpoint mapping.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.headers("X-API-Version:v1", "Accept-Language:en");

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.headers("Authorization:Bearer token", "X-Request-ID:12345");
`

consume

public Builder<E> consume(MediaType mediaType)

Add a single media type to the endpoint mapping that it can consume.

Example Usage

`// For a Servlet endpoint
WebEndpointMapping.Builder builder = WebEndpointMapping.servlet("myServlet");
builder.consume(MediaType.APPLICATION_JSON);

// For a WebFlux endpoint
WebEndpointMapping.Builder webFluxBuilder = WebEndpointMapping.webflux(handlerMethod);
webFluxBuilder.consume(MediaType.TEXT_PLAIN);
`

See Also

• jakarta.servlet.ServletRegistration
• jakarta.servlet.FilterRegistration
• jakarta.servlet.annotation.WebServlet
• jakarta.servlet.annotation.WebFilter
• org.springframework.web.servlet.DispatcherServlet
• org.springframework.web.reactive.DispatcherHandler
• org.springframework.web.servlet.HandlerMapping
• org.springframework.web.reactive.HandlerMapping
• RequestMapping
• org.springframework.web.servlet.mvc.method.RequestMappingInfo
• org.springframework.web.reactive.result.method.RequestMappingInfo

---

This documentation was auto-generated from the source code of microsphere-spring.