Package: ResponseBuilder

ResponseBuilder

Coverage

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