001/*
002 * Copyright (c) 2004-2010, Kohsuke Kawaguchi
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without modification, are permitted provided
006 * that the following conditions are met:
007 *
008 *     * Redistributions of source code must retain the above copyright notice, this list of
009 *       conditions and the following disclaimer.
010 *     * Redistributions in binary form must reproduce the above copyright notice, this list of
011 *       conditions and the following disclaimer in the documentation and/or other materials
012 *       provided with the distribution.
013 *
014 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
015 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
016 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
017 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
018 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
019 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
020 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
021 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
022 */
023
024package org.kohsuke.stapler;
025
026import net.sf.json.JsonConfig;
027import org.kohsuke.stapler.export.DataWriter;
028import org.kohsuke.stapler.export.ExportConfig;
029import org.kohsuke.stapler.export.Flavor;
030import org.kohsuke.stapler.export.Model;
031import org.kohsuke.stapler.export.NamedPathPruner;
032
033import javax.annotation.Nonnull;
034import javax.servlet.ServletException;
035import javax.servlet.http.HttpServletRequest;
036import javax.servlet.http.HttpServletResponse;
037import java.io.IOException;
038import java.io.InputStream;
039import java.io.OutputStream;
040import java.io.Writer;
041import java.net.URL;
042import java.net.URLConnection;
043
044/**
045 * Defines additional operations made available by Stapler.
046 *
047 * @see Stapler#getCurrentResponse()
048 * @author Kohsuke Kawaguchi
049 */
050public interface StaplerResponse extends HttpServletResponse {
051    /**
052     * Evaluates the url against the given object and
053     * forwards the request to the result.
054     *
055     * <p>
056     * This can be used for example inside an action method
057     * to forward a request to a JSP.
058     *
059     * @param it
060     *      the URL is evaluated against this object. Must not be null.
061     * @param url
062     *      the relative URL (e.g., "foo" or "foo/bar") to resolve
063     *      against the "it" object.
064     * @param request
065     *      Request to be forwarded.
066     */
067    void forward(Object it, String url, StaplerRequest request) throws ServletException, IOException;
068    /**
069     * Redirects the browser to where it came from (the referer.)
070     */
071    void forwardToPreviousPage(StaplerRequest request) throws ServletException, IOException;
072
073    /**
074     * Works like {@link #sendRedirect(String)} except that this method
075     * escapes the URL.
076     */
077    void sendRedirect2(@Nonnull String url) throws IOException;
078
079    /**
080     * Works like {@link #sendRedirect2(String)} but allows the caller to specify the HTTP status code.
081     */
082    void sendRedirect(int statusCore, @Nonnull String url) throws IOException;
083
084    /**
085     * Serves a static resource.
086     *
087     * <p>
088     * This method sets content type, HTTP status code, sends the complete data
089     * and closes the response. This method also handles cache-control HTTP headers
090     * like "If-Modified-Since" and others.
091     */
092    void serveFile(StaplerRequest request, URL res) throws ServletException, IOException;
093
094    void serveFile(StaplerRequest request, URL res, long expiration) throws ServletException, IOException;
095
096    /**
097     * Works like {@link #serveFile(StaplerRequest, URL)} but chooses the locale specific
098     * version of the resource if it's available. The convention of "locale specific version"
099     * is the same as that of property files.
100     * So Japanese resource for <tt>foo.html</tt> would be named <tt>foo_ja.html</tt>.
101     */
102    void serveLocalizedFile(StaplerRequest request, URL res) throws ServletException, IOException;
103
104    /**
105     * Works like {@link #serveFile(StaplerRequest, URL, long)} but chooses the locale
106     * specific version of the resource if it's available.
107     *
108     * See {@link #serveLocalizedFile(StaplerRequest, URL)} for more details.
109     */
110    void serveLocalizedFile(StaplerRequest request, URL res, long expiration) throws ServletException, IOException;
111
112    /**
113     * Serves a static resource.
114     *
115     * <p>
116     * This method works like {@link #serveFile(StaplerRequest, URL)} but this version
117     * allows the caller to fetch data from anywhere.
118     *
119     * @param data
120     *      {@link InputStream} that contains the data of the static resource.
121     * @param lastModified
122     *      The timestamp when the resource was last modified. See {@link URLConnection#getLastModified()}
123     *      for the meaning of the value. 0 if unknown, in which case "If-Modified-Since" handling
124     *      will not be performed.
125     * @param expiration
126     *      The number of milliseconds until the resource will "expire".
127     *      Until it expires the browser will be allowed to cache it
128     *      and serve it without checking back with the server.
129     *      After it expires, the client will send conditional GET to
130     *      check if the resource is actually modified or not.
131     *      If 0, it will immediately expire.
132     * @param contentLength
133     *      if the length of the input stream is known in advance, specify that value
134     *      so that HTTP keep-alive works. Otherwise specify -1 to indicate that the length is unknown.
135     * @param fileName
136     *      file name of this resource. Used to determine the MIME type.
137     *      Since the only important portion is the file extension, this could be just a file name,
138     *      or a full path name, or even a pseudo file name that doesn't actually exist.
139     *      It supports both '/' and '\\' as the path separator.
140     *
141     *      If this string starts with "mime-type:", like "mime-type:foo/bar", then "foo/bar" will
142     *      be used as a MIME type without consulting the servlet container.
143     */
144    void serveFile(StaplerRequest req, InputStream data, long lastModified, long expiration, long contentLength, String fileName) throws ServletException, IOException;
145
146    /**
147     * @deprecated use form with long contentLength
148     */
149    void serveFile(StaplerRequest req, InputStream data, long lastModified, long expiration, int contentLength, String fileName) throws ServletException, IOException;
150
151    /**
152     * Serves a static resource.
153     *
154     * Expiration date is set to the value that forces browser to do conditional GET
155     * for all resources.
156     *
157     * @see #serveFile(StaplerRequest, InputStream, long, long, int, String)
158     */
159    void serveFile(StaplerRequest req, InputStream data, long lastModified, long contentLength, String fileName) throws ServletException, IOException;
160
161    /**
162     * @deprecated use form with long contentLength
163     */
164    void serveFile(StaplerRequest req, InputStream data, long lastModified, int contentLength, String fileName) throws ServletException, IOException;
165
166    /**
167     * Serves the exposed bean in the specified flavor.
168     *
169     * <p>
170     * This method performs the complete output from the header to the response body.
171     * If the flavor is JSON, this method also supports JSONP via the {@code jsonp} query parameter.
172     * 
173     * <p>The {@code depth} parameter may be used to specify a recursion depth
174     * as in {@link Model#writeTo(Object,int,DataWriter)}.
175     * 
176     * <p>As of 1.146, the {@code tree} parameter may be used to control the output
177     * in detail; see {@link NamedPathPruner#NamedPathPruner(String)} for details.
178     *
179     * @deprecated Use {@link #serveExposedBean(StaplerRequest, Object, ExportConfig)}
180     */
181    @Deprecated
182    void serveExposedBean(StaplerRequest req, Object exposedBean, Flavor flavor) throws ServletException,IOException;
183
184    /**
185     * Serves the exposed bean in the specified flavor.
186     *
187     * <p>
188     * This method performs the complete output from the header to the response body.
189     * If the flavor is JSON, this method also supports JSONP via the {@code jsonp} query parameter.
190     *
191     * <p>The {@code depth} parameter may be used to specify a recursion depth
192     * as in {@link Model#writeTo(Object,int,DataWriter)}
193     *
194     * <p>As of 1.146, the {@code tree} parameter may be used to control the output
195     * in detail; see {@link NamedPathPruner#NamedPathPruner(String)} for details.
196     *
197     * <p> {@link ExportConfig} is passed by the caller to control serialization behavior
198     * @since 1.251
199     */
200    default void serveExposedBean(StaplerRequest req, Object exposedBean, ExportConfig exportConfig) throws ServletException,IOException {
201        serveExposedBean(req, exposedBean, exportConfig.getFlavor());
202    }
203
204    /**
205     * Works like {@link #getOutputStream()} but tries to send the response
206     * with gzip compression if the client supports it.
207     *
208     * <p>
209     * This method is useful for sending out a large text content.
210     *
211     * @param req
212     *      Used to determine whether the client supports compression
213     */
214    OutputStream getCompressedOutputStream(HttpServletRequest req) throws IOException;
215
216    /**
217     * Works like {@link #getCompressedOutputStream(HttpServletRequest)} but this
218     * method is for {@link #getWriter()}.
219     */
220    Writer getCompressedWriter(HttpServletRequest req) throws IOException;
221
222    /**
223     * Performs the reverse proxy to the given URL.
224     *
225     * @return
226     *      The status code of the response.
227     */
228    int reverseProxyTo(URL url, StaplerRequest req) throws IOException;
229
230    /**
231     * The JsonConfig to be used when serializing java beans from js bound methods to JSON.
232     * Setting this to null will make the default config to be used.
233     *
234     * @param config the config
235     */
236    void setJsonConfig(JsonConfig config);
237
238    /**
239     * The JsonConfig to be used when serializing java beans to JSON previously set by {@link #setJsonConfig(JsonConfig)}.
240     * Will return the default config if nothing has previously been set.
241     *
242     * @return the config
243     */
244    JsonConfig getJsonConfig();
245}