io.micronaut.web.router.Router Maven / Gradle / Ivy
/*
* Copyright 2017-2019 original authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.micronaut.web.router;
import io.micronaut.http.HttpMethod;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.filter.HttpFilter;
import javax.annotation.Nonnull;
import java.net.URI;
import java.util.List;
import java.util.Optional;
import java.util.stream.Stream;
/**
* Core Router interface that allows discovery of a route given an HTTP method and URI.
*
* @author Graeme Rocher
* @since 1.0
*/
@SuppressWarnings("MethodName")
public interface Router {
/**
* Find any {@link RouteMatch} regardless of HTTP method.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return A stream of route matches
*/
@Nonnull Stream> findAny(@Nonnull CharSequence uri);
/**
* Finds all of the possible routes for the given HTTP method and URI.
*
* @param httpMethod The HTTP method
* @param uri The URI route match
* @param The target type
* @param The type
* @return A {@link Stream} of possible {@link Route} instances.
*/
@Nonnull Stream> find(@Nonnull HttpMethod httpMethod, @Nonnull CharSequence uri);
/**
* Finds the closest match for the given request.
*
* @param request The request
* @param The target type
* @param The type
* @return A {@link List} of possible {@link Route} instances.
* @since 1.2.1
*/
@Nonnull List> findAllClosest(@Nonnull HttpRequest request);
/**
* Returns all UriRoutes.
*
* @return A {@link Stream} of all registered {@link UriRoute} instances.
*/
@Nonnull Stream uriRoutes();
/**
* Finds the first possible route for the given HTTP method and URI.
*
* @param httpMethod The HTTP method
* @param uri The URI
* @param The target type
* @param The URI route match
* @return The route match
*/
Optional> route(@Nonnull HttpMethod httpMethod, @Nonnull CharSequence uri);
/**
* Found a {@link RouteMatch} for the given {@link io.micronaut.http.HttpStatus} code.
*
* @param status The HTTP status
* @param The matched route
* @return The {@link RouteMatch}
*/
Optional> route(@Nonnull HttpStatus status);
/**
* Found a {@link RouteMatch} for the given {@link io.micronaut.http.HttpStatus} code.
*
* @param originatingClass The class the error originates from
* @param status The HTTP status
* @param The matched route
* @return The {@link RouteMatch}
*/
Optional> route(@Nonnull Class originatingClass, @Nonnull HttpStatus status);
/**
* Match a route to an error.
*
* @param error The error
* @param The matched route
* @return The {@link RouteMatch}
*/
Optional> route(@Nonnull Throwable error);
/**
* Match a route to an error.
*
* @param originatingClass The class the error originates from
* @param error The error
* @param The matched route
* @return The {@link RouteMatch}
*/
Optional> route(@Nonnull Class originatingClass, @Nonnull Throwable error);
/**
* Build a filtered {@link org.reactivestreams.Publisher} for an action.
*
* @param request The request
* @return A new filtered publisher
*/
@Nonnull List findFilters(
@Nonnull HttpRequest request
);
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#GET} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> GET(@Nonnull CharSequence uri) {
return route(HttpMethod.GET, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#POST} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> POST(@Nonnull CharSequence uri) {
return route(HttpMethod.POST, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#PUT} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The URI route match
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> PUT(@Nonnull CharSequence uri) {
return route(HttpMethod.PUT, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#PATCH} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> PATCH(@Nonnull CharSequence uri) {
return route(HttpMethod.PATCH, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#DELETE} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> DELETE(@Nonnull CharSequence uri) {
return route(HttpMethod.DELETE, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#OPTIONS} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> OPTIONS(@Nonnull CharSequence uri) {
return route(HttpMethod.OPTIONS, uri);
}
/**
* Find the first {@link RouteMatch} route for an {@link HttpMethod#HEAD} method and the given URI.
*
* @param uri The URI
* @param The target type
* @param The return type
* @return An {@link Optional} of {@link RouteMatch}
*/
default Optional> HEAD(@Nonnull CharSequence uri) {
return route(HttpMethod.HEAD, uri);
}
/**
* Finds all of the possible routes for the given HTTP method and URI.
*
* @param httpMethod The HTTP method
* @param uri The URI
* @param The target type
* @param The URI route match
* @return A {@link Stream} of possible {@link Route} instances.
*/
default @Nonnull Stream> find(@Nonnull HttpMethod httpMethod, @Nonnull URI uri) {
return find(httpMethod, uri.toString());
}
/**
* Finds all of the possible routes for the given HTTP request.
*
* @param request The HTTP request
* @param The target type
* @param The URI route match
* @return A {@link Stream} of possible {@link Route} instances.
*/
default @Nonnull Stream> find(@Nonnull HttpRequest request) {
return find(request.getMethod(), request.getPath());
}
}