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-2021 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}