001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: Response.java 3634 2007-01-08 21:42:24Z gbevin $
007: */
008: package com.uwyn.rife.engine;
009:
010: import com.uwyn.rife.engine.exceptions.EngineException;
011: import com.uwyn.rife.template.Template;
012: import java.io.IOException;
013: import java.io.OutputStream;
014: import java.io.PrintWriter;
015: import java.util.ArrayList;
016: import java.util.Collection;
017: import java.util.Locale;
018: import javax.servlet.http.Cookie;
019: import javax.servlet.http.HttpServletResponse;
020:
021: /**
022: * This interface contains all the methods that the web engine needs to be
023: * able to send a response to the client.
024: *
025: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
026: * @version $Revision: 3634 $
027: * @since 1.1
028: */
029: public interface Response {
030: /**
031: * Creates a new <code>Response</code> instance that will be used for
032: * embedded elements.
033: *
034: * @param valueId the template value in which the embedded element will
035: * be processed
036: * @param differentiator the embedded element differentiator
037: * @return the new <code>Response</code> instance for embedded use
038: * @since 1.5
039: */
040: public Response createEmbeddedResponse(String valueId,
041: String differentiator);
042:
043: /**
044: * Retrieves the content of the response for embedded usage and
045: * integration into another response.
046: *
047: * @return the embedded content; or
048: * <p><code>null</code> if the response is not embedded.
049: * @since 1.1
050: */
051: public ArrayList<CharSequence> getEmbeddedContent();
052:
053: /**
054: * Indicates whether this response is embedded into another response.
055: *
056: * @return <code>true</code> if the response is embedded; or
057: * <p><code>false</code> otherwise.
058: * @since 1.1
059: */
060: public boolean isEmbedded();
061:
062: /**
063: * Sets the latest target element of this response. This method is called
064: * repeatedly by the engine to make it possible to trace which elements
065: * have been processed.
066: *
067: * @param element an element that has been executed in the context of this
068: * response
069: * @since 1.1
070: */
071: public void setLastElement(ElementSupport element);
072:
073: /**
074: * Enables or disabled the text output buffer.
075: * <p>The buffer is enabled by default and its buffered contents will be
076: * flushed when the buffer is disabled.
077: *
078: * @param enabled <code>true</code> to enable the text buffer; or
079: * <p><code>false</code> to disable it
080: * @since 1.1
081: */
082: public void enableTextBuffer(boolean enabled);
083:
084: /**
085: * Indicates whether the text output buffer is enabled.
086: *
087: * @return <code>true</code> when the text buffer is enabled; or
088: * <p><code>false</code> when it is disabled.
089: * @since 1.1
090: */
091: public boolean isTextBufferEnabled();
092:
093: /**
094: * Prints the content of a template to the request text output.
095: *
096: * @param template the template that will be printed
097: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
098: * occurs during the output of the template content
099: * @see #print(Collection)
100: * @see #print(Object)
101: * @since 1.1
102: */
103: public void print(Template template) throws EngineException;
104:
105: /**
106: * Prints a list of text snippets to the request text output.
107: *
108: * @param deferredContent the text snippets that will be printed
109: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
110: * occurs during the output of the text snippets
111: * @see #print(Template)
112: * @see #print(Object)
113: * @since 1.1
114: */
115: public void print(Collection<CharSequence> deferredContent)
116: throws EngineException;
117:
118: /**
119: * Prints the string representation of an object to the request text
120: * output. The string representation will be created through a
121: * <code>String.valueOf(value)</code> call.
122: *
123: * @param value the object that will be output
124: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
125: * occurs during the output of the content
126: * @see #print(Template)
127: * @see #print(Collection)
128: * @since 1.1
129: */
130: public void print(Object value) throws EngineException;
131:
132: /**
133: * Clears the text buffer is it's enabled.
134: * <p>If the text buffer is disabled, this method does nothing.
135: *
136: * @since 1.1
137: */
138: public void clearBuffer();
139:
140: /**
141: * Forces all the streamed content to be output to the client.
142: * <p>If the text buffer is enabled, this will flush its content to the
143: * output stream first.
144: *
145: * @since 1.1
146: */
147: public void flush() throws EngineException;
148:
149: /**
150: * Closed the content output stream.
151: * <p>All content is {@link #flush flushed} first.
152: *
153: * @since 1.1
154: */
155: public void close() throws EngineException;
156:
157: /**
158: * See {@link HttpServletResponse#getOutputStream()}.
159: *
160: * @since 1.1
161: */
162: public OutputStream getOutputStream() throws EngineException;
163:
164: /**
165: * See {@link HttpServletResponse#getWriter()}.
166: *
167: * @since 1.1
168: */
169: public PrintWriter getWriter() throws IOException;
170:
171: /**
172: * See {@link HttpServletResponse#setContentType(String)}.
173: *
174: * @since 1.1
175: */
176: public void setContentType(String contentType);
177:
178: /**
179: * Indicates whether this response's content type has been explicitly
180: * set.
181: *
182: * @return <code>true</code> if it has been set; or
183: * <p><code>false</code> otherwise
184: *
185: * @see #setContentType
186: * @since 1.3
187: */
188: public boolean isContentTypeSet();
189:
190: /**
191: * Retrieves the content type that was explicitly set for this response.
192: *
193: * @return the content type as a String; or
194: * <p><code>null</code> if the content type wasn't set
195: *
196: * @see #setContentType
197: * @since 1.5.1
198: */
199: public String getContentType();
200:
201: /**
202: * See {@link HttpServletResponse#setLocale(Locale)}.
203: *
204: * @since 1.1
205: */
206: public void setLocale(Locale locale);
207:
208: /**
209: * See {@link HttpServletResponse#getLocale()}.
210: *
211: * @since 1.1
212: */
213: public Locale getLocale();
214:
215: /**
216: * See {@link HttpServletResponse#getCharacterEncoding()}.
217: *
218: * @since 1.1
219: */
220: public String getCharacterEncoding();
221:
222: /**
223: * See {@link HttpServletResponse#setContentLength(int)}.
224: *
225: * @since 1.1
226: */
227: public void setContentLength(int length) throws EngineException;
228:
229: /**
230: * See {@link HttpServletResponse#addCookie(Cookie)}.
231: *
232: * @since 1.1
233: */
234: public void addCookie(Cookie cookie);
235:
236: /**
237: * See {@link HttpServletResponse#addHeader(String, String)}.
238: *
239: * @since 1.1
240: */
241: public void addHeader(String name, String value);
242:
243: /**
244: * See {@link HttpServletResponse#addDateHeader(String, long)}.
245: *
246: * @since 1.1
247: */
248: public void addDateHeader(String name, long date);
249:
250: /**
251: * See {@link HttpServletResponse#addIntHeader(String, int)}.
252: *
253: * @since 1.1
254: */
255: public void addIntHeader(String name, int integer);
256:
257: /**
258: * See {@link HttpServletResponse#containsHeader(String)}.
259: *
260: * @since 1.1
261: */
262: public boolean containsHeader(String name);
263:
264: /**
265: * See {@link HttpServletResponse#sendError(int)}.
266: *
267: * @since 1.1
268: */
269: public void sendError(int statusCode) throws EngineException;
270:
271: /**
272: * See {@link HttpServletResponse#sendError(int, String)}.
273: *
274: * @since 1.1
275: */
276: public void sendError(int statusCode, String message)
277: throws EngineException;
278:
279: /**
280: * See {@link HttpServletResponse#sendRedirect(String)}.
281: *
282: * @since 1.1
283: */
284: public void sendRedirect(String location) throws EngineException;
285:
286: /**
287: * See {@link HttpServletResponse#setDateHeader(String, long)}.
288: *
289: * @since 1.1
290: */
291: public void setDateHeader(String name, long date);
292:
293: /**
294: * See {@link HttpServletResponse#setHeader(String, String)}.
295: *
296: * @since 1.1
297: */
298: public void setHeader(String name, String value);
299:
300: /**
301: * See {@link HttpServletResponse#setIntHeader(String, int)}.
302: *
303: * @since 1.1
304: */
305: public void setIntHeader(String name, int value);
306:
307: /**
308: * See {@link HttpServletResponse#setStatus(int)}.
309: *
310: * @since 1.1
311: */
312: public void setStatus(int statusCode);
313:
314: /**
315: * See {@link HttpServletResponse#encodeURL(String)}.
316: *
317: * @since 1.1
318: */
319: public String encodeURL(String url);
320:
321: /**
322: * Retrieves the underlying {@link HttpServletResponse}.
323: *
324: * @return the underlying <code>HttpServletResponse</code> instance; or
325: * <p><code>null</code> if this response isn't backed by
326: * <code>HttpServletResponse</code>
327: * @since 1.1
328: */
329: public HttpServletResponse getHttpServletResponse();
330: }
|