001/* 002 * Copyright 2002-2020 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.http.server.reactive; 018 019import java.net.InetSocketAddress; 020import java.net.URI; 021import java.util.function.Consumer; 022 023import org.springframework.http.HttpCookie; 024import org.springframework.http.HttpHeaders; 025import org.springframework.http.HttpMethod; 026import org.springframework.http.HttpRequest; 027import org.springframework.http.ReactiveHttpInputMessage; 028import org.springframework.http.server.RequestPath; 029import org.springframework.lang.Nullable; 030import org.springframework.util.MultiValueMap; 031 032/** 033 * Represents a reactive server-side HTTP request. 034 * 035 * @author Arjen Poutsma 036 * @author Rossen Stoyanchev 037 * @author Sam Brannen 038 * @since 5.0 039 */ 040public interface ServerHttpRequest extends HttpRequest, ReactiveHttpInputMessage { 041 042 /** 043 * Return an id that represents the underlying connection, if available, 044 * or the request for the purpose of correlating log messages. 045 * @since 5.1 046 * @see org.springframework.web.server.ServerWebExchange#getLogPrefix() 047 */ 048 String getId(); 049 050 /** 051 * Returns a structured representation of the request path including the 052 * context path + path within application portions, path segments with 053 * encoded and decoded values, and path parameters. 054 */ 055 RequestPath getPath(); 056 057 /** 058 * Return a read-only map with parsed and decoded query parameter values. 059 */ 060 MultiValueMap<String, String> getQueryParams(); 061 062 /** 063 * Return a read-only map of cookies sent by the client. 064 */ 065 MultiValueMap<String, HttpCookie> getCookies(); 066 067 /** 068 * Return the local address the request was accepted on, if available. 069 * @since 5.2.3 070 */ 071 @Nullable 072 default InetSocketAddress getLocalAddress() { 073 return null; 074 } 075 076 /** 077 * Return the remote address where this request is connected to, if available. 078 */ 079 @Nullable 080 default InetSocketAddress getRemoteAddress() { 081 return null; 082 } 083 084 /** 085 * Return the SSL session information if the request has been transmitted 086 * over a secure protocol including SSL certificates, if available. 087 * @return the session information, or {@code null} if none available 088 * @since 5.0.2 089 */ 090 @Nullable 091 default SslInfo getSslInfo() { 092 return null; 093 } 094 095 /** 096 * Return a builder to mutate properties of this request by wrapping it 097 * with {@link ServerHttpRequestDecorator} and returning either mutated 098 * values or delegating back to this instance. 099 */ 100 default ServerHttpRequest.Builder mutate() { 101 return new DefaultServerHttpRequestBuilder(this); 102 } 103 104 105 /** 106 * Builder for mutating an existing {@link ServerHttpRequest}. 107 */ 108 interface Builder { 109 110 /** 111 * Set the HTTP method to return. 112 */ 113 Builder method(HttpMethod httpMethod); 114 115 /** 116 * Set the URI to use with the following conditions: 117 * <ul> 118 * <li>If {@link #path(String) path} is also set, it overrides the path 119 * of the URI provided here. 120 * <li>If {@link #contextPath(String) contextPath} is also set, or 121 * already present, it must match the start of the path of the URI 122 * provided here. 123 * </ul> 124 */ 125 Builder uri(URI uri); 126 127 /** 128 * Set the path to use instead of the {@code "rawPath"} of the URI of 129 * the request with the following conditions: 130 * <ul> 131 * <li>If {@link #uri(URI) uri} is also set, the path given here 132 * overrides the path of the given URI. 133 * <li>If {@link #contextPath(String) contextPath} is also set, or 134 * already present, it must match the start of the path given here. 135 * <li>The given value must begin with a slash. 136 * </ul> 137 */ 138 Builder path(String path); 139 140 /** 141 * Set the contextPath to use. 142 * <p>The given value must be a valid {@link RequestPath#contextPath() 143 * contextPath} and it must match the start of the path of the URI of 144 * the request. That means changing the contextPath, implies also 145 * changing the path via {@link #path(String)}. 146 */ 147 Builder contextPath(String contextPath); 148 149 /** 150 * Set or override the specified header values under the given name. 151 * <p>If you need to add header values, remove headers, etc., use 152 * {@link #headers(Consumer)} for greater control. 153 * @param headerName the header name 154 * @param headerValues the header values 155 * @since 5.1.9 156 * @see #headers(Consumer) 157 */ 158 Builder header(String headerName, String... headerValues); 159 160 /** 161 * Manipulate request headers. The provided {@code HttpHeaders} contains 162 * current request headers, so that the {@code Consumer} can 163 * {@linkplain HttpHeaders#set(String, String) overwrite} or 164 * {@linkplain HttpHeaders#remove(Object) remove} existing values, or 165 * use any other {@link HttpHeaders} methods. 166 * @see #header(String, String...) 167 */ 168 Builder headers(Consumer<HttpHeaders> headersConsumer); 169 170 /** 171 * Set the SSL session information. This may be useful in environments 172 * where TLS termination is done at the router, but SSL information is 173 * made available in some other way such as through a header. 174 * @since 5.0.7 175 */ 176 Builder sslInfo(SslInfo sslInfo); 177 178 /** 179 * Build a {@link ServerHttpRequest} decorator with the mutated properties. 180 */ 181 ServerHttpRequest build(); 182 } 183 184}