Package: ResponseBuilder

ResponseBuilder

Coverage

1: /*
2: * #%L
3: * *********************************************************************************************************************
4: *
5: * NorthernWind - lightweight CMS
6: * http://northernwind.tidalwave.it - git clone https://bitbucket.org/tidalwave/northernwind-src.git
7: * %%
8: * Copyright (C) 2011 - 2023 Tidalwave s.a.s. (http://tidalwave.it)
9: * %%
10: * *********************************************************************************************************************
11: *
12: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
13: * the License. You may obtain a copy of the License at
14: *
15: * http://www.apache.org/licenses/LICENSE-2.0
16: *
17: * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
18: * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
19: * specific language governing permissions and limitations under the License.
20: *
21: * *********************************************************************************************************************
22: *
23: *
24: * *********************************************************************************************************************
25: * #L%
26: */
27: package it.tidalwave.northernwind.core.model.spi;
28:
29: import javax.annotation.Nonnull;
30: import java.time.Duration;
31: import java.time.ZonedDateTime;
32: import java.util.Map;
33: import java.io.IOException;
34: import it.tidalwave.util.NotFoundException;
35: import it.tidalwave.northernwind.core.model.HttpStatusException;
36: import it.tidalwave.northernwind.core.model.Request;
37: import it.tidalwave.northernwind.core.model.ResourceFile;
38:
39: /***********************************************************************************************************************
40: *
41: * A builder of a response.
42: *
43: * @param <RESPONSE_TYPE> the produced response (may change in function of the technology used for serving the
44: * results)
45: * @author Fabrizio Giudici
46: *
47: **********************************************************************************************************************/
48: public interface ResponseBuilder<RESPONSE_TYPE>
49: {
50: /*******************************************************************************************************************
51: *
52: * Sets a header.
53: *
54: * @param header the header name
55: * @param value the header value
56: * @return itself for fluent interface style
57: *
58: ******************************************************************************************************************/
59: @Nonnull
60: public ResponseBuilder<RESPONSE_TYPE> withHeader (@Nonnull String header, @Nonnull String value);
61:
62: /*******************************************************************************************************************
63: *
64: * Sets multiple headers at the same time.
65: *
66: * @param headers the headers
67: * @return itself for fluent interface style
68: *
69: ******************************************************************************************************************/
70: @Nonnull
71: public ResponseBuilder<RESPONSE_TYPE> withHeaders (@Nonnull Map<String, String> headers);
72:
73: /*******************************************************************************************************************
74: *
75: * Specifies the content type.
76: *
77: * @param contentType the content type
78: * @return itself for fluent interface style
79: *
80: ******************************************************************************************************************/
81: @Nonnull
82: public ResponseBuilder<RESPONSE_TYPE> withContentType (@Nonnull String contentType);
83:
84: /*******************************************************************************************************************
85: *
86: * Specifies the content length.
87: *
88: * @param contentLength the content length
89: * @return itself for fluent interface style
90: *
91: ******************************************************************************************************************/
92: @Nonnull
93: public ResponseBuilder<RESPONSE_TYPE> withContentLength (long contentLength);
94:
95: /*******************************************************************************************************************
96: *
97: * Specifies the content disposition.
98: *
99: * @param contentDisposition the content disposition
100: * @return itself for fluent interface style
101: *
102: ******************************************************************************************************************/
103: @Nonnull
104: public ResponseBuilder<RESPONSE_TYPE> withContentDisposition (@Nonnull String contentDisposition);
105:
106: /*******************************************************************************************************************
107: *
108: * Specifies the expiration time.
109: *
110: * @param duration the duration
111: * @return itself for fluent interface style
112: *
113: ******************************************************************************************************************/
114: @Nonnull
115: public ResponseBuilder<RESPONSE_TYPE> withExpirationTime (@Nonnull Duration duration);
116:
117: /*******************************************************************************************************************
118: *
119: * Specifies the latest modified time.
120: *
121: * @param time the time
122: * @return itself for fluent interface style
123: *
124: ******************************************************************************************************************/
125: @Nonnull
126: public ResponseBuilder<RESPONSE_TYPE> withLatestModifiedTime (@Nonnull ZonedDateTime time);
127:
128: /*******************************************************************************************************************
129: *
130: * Specifies the body of the response. Accepted objects are: {@code byte[]}, {@code String},
131: * {@code InputStream}.
132: *
133: * @param body the body
134: * @return itself for fluent interface style
135: *
136: ******************************************************************************************************************/
137: @Nonnull
138: public ResponseBuilder<RESPONSE_TYPE> withBody (@Nonnull Object body);
139:
140: /*******************************************************************************************************************
141: *
142: * Specifies the body of the response as a {@link ResourceFile}.
143: *
144: * @param file the file
145: * @return itself for fluent interface style
146: * @throws IOException if an error occurs when reading the file
147: *
148: ******************************************************************************************************************/
149: @Nonnull
150: public ResponseBuilder<RESPONSE_TYPE> fromFile (@Nonnull ResourceFile file)
151: throws IOException;
152:
153: /*******************************************************************************************************************
154: *
155: * Specifies the {@link Request} we're serving - this makes it possible to read some headers and other
156: * configurations needed e.g. for cache control.
157: *
158: * @param request the request
159: * @return itself for fluent interface style
160: *
161: ******************************************************************************************************************/
162: @Nonnull
163: public ResponseBuilder<RESPONSE_TYPE> forRequest (@Nonnull Request request);
164:
165: /*******************************************************************************************************************
166: *
167: * Specifies an exception to create the response from.
168: *
169: * @param e the exception
170: * @return itself for fluent interface style
171: *
172: ******************************************************************************************************************/
173: @Nonnull
174: public ResponseBuilder<RESPONSE_TYPE> forException (@Nonnull NotFoundException e);
175:
176: /*******************************************************************************************************************
177: *
178: * Specifies an exception to create the response from.
179: *
180: * @param e the exception
181: * @return itself for fluent interface style
182: *
183: ******************************************************************************************************************/
184: @Nonnull
185: public ResponseBuilder<RESPONSE_TYPE> forException (@Nonnull HttpStatusException e);
186:
187: /*******************************************************************************************************************
188: *
189: * Specifies an exception to create the response from.
190: *
191: * @param e the exception
192: * @return itself for fluent interface style
193: *
194: ******************************************************************************************************************/
195: @Nonnull
196: public ResponseBuilder<RESPONSE_TYPE> forException (@Nonnull Throwable e);
197:
198: /*******************************************************************************************************************
199: *
200: * Specifies the HTTP status.
201: *
202: * @param httpStatus the status
203: * @return itself for fluent interface style
204: *
205: ******************************************************************************************************************/
206: @Nonnull
207: public ResponseBuilder<RESPONSE_TYPE> withStatus (int httpStatus);
208:
209: /*******************************************************************************************************************
210: *
211: * Creates a builder for a permanent redirect.
212: *
213: * @param url the URL of the redirect
214: * @return itself for fluent interface style
215: *
216: ******************************************************************************************************************/
217: @Nonnull
218: public ResponseBuilder<RESPONSE_TYPE> permanentRedirect (@Nonnull String url);
219:
220: /*******************************************************************************************************************
221: *
222: * Builds the response.
223: *
224: * @return the response
225: *
226: ******************************************************************************************************************/
227: @Nonnull
228: public RESPONSE_TYPE build();
229:
230: /*******************************************************************************************************************
231: *
232: *
233: *
234: ******************************************************************************************************************/
235: public void put();
236: }
237: