1 /*
2 * Copyright (c) 2011-2022, jcabi.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met: 1) Redistributions of source code must retain the above
8 * copyright notice, this list of conditions and the following
9 * disclaimer. 2) Redistributions in binary form must reproduce the above
10 * copyright notice, this list of conditions and the following
11 * disclaimer in the documentation and/or other materials provided
12 * with the distribution. 3) Neither the name of the jcabi.com nor
13 * the names of its contributors may be used to endorse or promote
14 * products derived from this software without specific prior written
15 * permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package com.jcabi.http;
31
32 import com.jcabi.aspects.Immutable;
33 import java.net.URI;
34 import java.util.Map;
35
36 /**
37 * Request URI.
38 *
39 * <p>Instance of this interface is returned by {@link Request#uri()},
40 * and can be modified using one of the methods below. When modification
41 * is done, method {@code back()} returns a modified instance of
42 * {@link Request}, for example:
43 *
44 * <pre> new JdkRequest("http://my.example.com")
45 * .header("Accept", "application/json")
46 * .uri()
47 * .path("/users")
48 * .queryParam("name", "Jeff Lebowski")
49 * .back() // returns a modified instance of Request
50 * .fetch()</pre>
51 *
52 * <p>Instances of this interface are immutable and thread-safe.
53 *
54 * @since 0.8
55 * @checkstyle AbbreviationAsWordInNameCheck (100 lines)
56 */
57 @Immutable
58 public interface RequestURI {
59
60 /**
61 * Get back to the request it's related to.
62 * @return The request we're in
63 */
64 Request back();
65
66 /**
67 * Get URI.
68 * @return The destination it is currently pointing to
69 */
70 URI get();
71
72 /**
73 * Set URI.
74 * @param uri URI to set
75 * @return New alternated URI
76 */
77 RequestURI set(URI uri);
78
79 /**
80 * Add query param.
81 * @param name Query param name
82 * @param value Value of the query param to set
83 * @return New alternated URI
84 */
85 RequestURI queryParam(String name, Object value);
86
87 /**
88 * Add query params.
89 * @param map Map of params to add
90 * @return New alternated URI
91 */
92 RequestURI queryParams(Map<String, String> map);
93
94 /**
95 * Add URI path.
96 * @param segment Path segment to add
97 * @return New alternated URI
98 */
99 RequestURI path(String segment);
100
101 /**
102 * Set user info.
103 * @param info User info part to set
104 * @return New alternated URI
105 */
106 RequestURI userInfo(String info);
107
108 /**
109 * Set port number.
110 * @param num The port number to set
111 * @return New altered URI
112 */
113 RequestURI port(int num);
114
115 }