001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * http://www.opensource.org/licenses/cddl1.php. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file. If applicable, add the following below this CDDL HEADER, 016 * with the fields enclosed by brackets "[]" replaced with your own 017 * identifying information: 018 * Portions Copyright [yyyy] [name of copyright owner] 019 * 020 * CDDL HEADER END 021 * 022 * 023 * Copyright 2019-2020 Ping Identity Corporation 024 */ 025package com.unboundid.directory.sdk.broker.types; 026 027import com.fasterxml.jackson.databind.JsonNode; 028 029import javax.ws.rs.core.MultivaluedMap; 030import java.net.URI; 031import java.net.URISyntaxException; 032import java.util.List; 033import java.util.Map; 034 035/** 036 * Generically represents an HTTP request or response to/from a DataGovernance 037 * endpoint on which an advice can operate. 038 */ 039public interface HttpRequestResponse 040{ 041 /** 042 * Get the URL that this request is pointed at, or null if a response. 043 * 044 * @return The request URL (nullable). 045 */ 046 URI getUrl(); 047 048 /** 049 * Get the URL that this request is pointed at, formatted as a string, or 050 * null if a response. 051 * 052 * @return The request URL (nullable). 053 */ 054 String getUrlString(); 055 056 /** 057 * Set this request's URL. 058 * 059 * @param url The request URL. 060 */ 061 void setUrl(URI url); 062 063 /** 064 * Get the request's query parameters parsed as a map. Modifying the map will 065 * not modify this request; use this class's methods to set the request 066 * parameters. If there are no query parameters, or this object represents a 067 * response, an empty map will be returned. 068 * 069 * @return The request query params. 070 */ 071 MultivaluedMap<String, String> getQueryParams(); 072 073 /** 074 * Get the value(s) of a specific query parameter. Modifying the returned 075 * list will not modify this request; use this class's methods to set the 076 * request parameters. 077 * 078 * @param key The query parameter to look up. 079 * @return The value of the parameter, or null if it is not present. 080 */ 081 List<String> getQueryParam(String key); 082 083 /** 084 * Set the query parameters of this request. 085 * 086 * @param params The parameters to provide. 087 * @throws URISyntaxException If the query parameters cannot be formatted. 088 */ 089 void setQueryParams(Map<String, List<String>> params) 090 throws URISyntaxException; 091 092 /** 093 * Set the query parameters of this request. 094 * 095 * @param params The parameters to provide. 096 * @throws URISyntaxException If the query parameters cannot be formatted. 097 */ 098 void setQueryParams(MultivaluedMap<String, String> params) 099 throws URISyntaxException; 100 101 /** 102 * Set the value(s) of a specific query parameter. To remove a parameter 103 * from the list, set the values to null. 104 * 105 * @param key The parameter to set. 106 * @param values The values to set the parameter to. 107 * @throws URISyntaxException If the query parameters cannot be formatted. 108 */ 109 void setQueryParam(String key, List<String> values) 110 throws URISyntaxException; 111 112 /** 113 * Set a specific query parameter to a single value. Setting null will 114 * result in an empty parameter. 115 * 116 * @param key The parameter to set. 117 * @param value The value to set the parameter to. 118 * @throws URISyntaxException If the query parameters cannot be formatted. 119 */ 120 void setQueryParam(String key, String value) throws URISyntaxException; 121 122 /** 123 * Add a new value to the query parameter. Passing null will result in an 124 * empty parameter. 125 * @param key The parameter to set. 126 * @param value The value to set the parameter to. 127 * @throws URISyntaxException If the query parameters cannot be formatted. 128 */ 129 void addQueryParam(String key, String value) throws URISyntaxException; 130 131 /** 132 * Get a copy of the headers provided to this request/response. Modifying the 133 * map will not modify the request/response; use this class's methods to set 134 * the request/response headers. If no headers were provided, an empty map 135 * will be returned. 136 * 137 * @return The request or response headers. 138 */ 139 MultivaluedMap<String, String> getHeaders(); 140 141 /** 142 * Get the values of a header provided to this request/response. 143 * 144 * @param key The header to retrieve. 145 * @return The values of the header, or null if the header is not present. 146 */ 147 List<String> getHeader(String key); 148 149 /** 150 * Get the value of a header provided to this request/response. If the header 151 * has been provided multiple times, it will be concatenated with a semicolon. 152 * 153 * @param key The header to retrieve. 154 * @return The concatenated value of the header, or null if the header is 155 * not present. 156 */ 157 String getHeaderString(String key); 158 159 /** 160 * Set the request or response headers. 161 * 162 * @param headers The headers to set. 163 */ 164 void setHeaders(MultivaluedMap<String, String> headers); 165 166 /** 167 * Set the value of a header to a single value. 168 * 169 * @param key The header to set. 170 * @param value The header value to set. 171 */ 172 void setHeader(String key, String value); 173 174 /** 175 * Set the value of a header to multiple values. 176 * 177 * @param key The header to set. 178 * @param value The header values to set. 179 */ 180 void setHeader(String key, List<String> value); 181 182 /** 183 * Add a value to a header. 184 * 185 * @param key The header to modify. 186 * @param value The value to add. 187 */ 188 void addHeader(String key, String value); 189 190 /** 191 * Get the parsed JSON body of the request/response. May be null if the 192 * request or response does not have a body (such as a GET request). 193 * 194 * @return The request or response body (nullable). 195 */ 196 JsonNode getBody(); 197 198 /** 199 * Set the contents of the request/response body. 200 * 201 * @param body The request or response body. 202 */ 203 void setBody(JsonNode body); 204 205 /** 206 * Create a new HttpRequestResponse containing deep copies of this object's 207 * values. 208 * 209 * @return A cloned HttpRequestResponse. 210 */ 211 HttpRequestResponse copy(); 212}