1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package javax.portlet;
22
23
24 /***
25 * The <CODE>RenderResponse</CODE> defines an object to assist a portlet in
26 * sending a response to the portal.
27 * It extends the <CODE>PortletResponse</CODE> interface to provide specific
28 * render response functionality to portlets.<br>
29 * The portlet container creates a <CODE>RenderResponse</CODE> object and
30 * passes it as argument to the portlet's <CODE>render</CODE> method.
31 *
32 * @see RenderRequest
33 * @see PortletResponse
34 */
35 public interface RenderResponse extends PortletResponse
36 {
37
38
39 /***
40 * Property to set the expiration time in seconds for this
41 * response using the <code>setProperty</code> method.
42 * <P>
43 * If the expiration value is set to 0, caching is disabled
44 * for this portlet; if the value is set to -1,
45 * the cache does not expire.
46 * <p>
47 * The value is <code>"portlet.expiration-cache"</code>.
48 */
49 public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
50
51 /***
52 * Returns the MIME type that can be used to contribute
53 * markup to the render response.
54 * <p>
55 * If no content type was set previously using the {@link #setContentType} method
56 * this method retuns <code>null</code>.
57 *
58 * @see #setContentType
59 *
60 * @return the MIME type of the response, or <code>null</code>
61 * if no content type is set
62 */
63
64 public String getContentType ();
65
66
67 /***
68 * Creates a portlet URL targeting the portlet. If no portlet mode,
69 * window state or security modifier is set in the PortletURL the
70 * current values are preserved. If a request is triggered by the
71 * PortletURL, it results in a render request.
72 * <p>
73 * The returned URL can be further extended by adding
74 * portlet-specific parameters and portlet modes and window states.
75 * <p>
76 * The created URL will per default not contain any parameters
77 * of the current render request.
78 *
79 * @return a portlet render URL
80 */
81 public PortletURL createRenderURL ();
82
83
84 /***
85 * Creates a portlet URL targeting the portlet. If no portlet mode,
86 * window state or security modifier is set in the PortletURL the
87 * current values are preserved. If a request is triggered by the
88 * PortletURL, it results in an action request.
89 * <p>
90 * The returned URL can be further extended by adding
91 * portlet-specific parameters and portlet modes and window states.
92 * <p>
93 * The created URL will per default not contain any parameters
94 * of the current render request.
95 *
96 * @return a portlet action URL
97 */
98 public PortletURL createActionURL ();
99
100
101
102 /***
103 * The value returned by this method should be prefixed or appended to
104 * elements, such as JavaScript variables or function names, to ensure
105 * they are unique in the context of the portal page.
106 *
107 * @return the namespace
108 */
109
110 public String getNamespace ();
111
112
113
114 /***
115 * This method sets the title of the portlet.
116 * <p>
117 * The value can be a text String
118 *
119 * @param title portlet title as text String or resource URI
120 */
121
122 public void setTitle(String title);
123
124
125
126
127 /***
128 * Sets the MIME type for the render response. The portlet must
129 * set the content type before calling {@link #getWriter} or
130 * {@link #getPortletOutputStream}.
131 * <p>
132 * Calling <code>setContentType</code> after <code>getWriter</code>
133 * or <code>getOutputStream</code> does not change the content type.
134 *
135 * @param type the content MIME type
136 *
137 * @throws java.lang.IllegalArgumentException
138 * if the given type is not in the list returned
139 * by <code>PortletRequest.getResponseContentTypes</code>
140 *
141 * @see RenderRequest#getResponseContentTypes
142 * @see #getContentType
143 */
144
145 public void setContentType(String type);
146
147
148 /***
149 * Returns the name of the charset used for
150 * the MIME body sent in this response.
151 *
152 * <p>See <a href="http://ds.internic.net/rfc/rfc2045.txt">RFC 2047</a>
153 * for more information about character encoding and MIME.
154 *
155 * @return a <code>String</code> specifying the
156 * name of the charset, for
157 * example, <code>ISO-8859-1</code>
158 *
159 */
160
161 public String getCharacterEncoding();
162
163
164 /***
165 * Returns a PrintWriter object that can send character
166 * text to the portal.
167 * <p>
168 * Before calling this method the content type of the
169 * render response must be set using the {@link #setContentType}
170 * method.
171 * <p>
172 * Either this method or {@link #getPortletOutputStream} may be
173 * called to write the body, not both.
174 *
175 * @return a <code>PrintWriter</code> object that
176 * can return character data to the portal
177 *
178 * @exception java.io.IOException
179 * if an input or output exception occurred
180 * @exception java.lang.IllegalStateException
181 * if the <code>getPortletOutputStream</code> method
182 * has been called on this response,
183 * or if no content type was set using the
184 * <code>setContentType</code> method.
185 *
186 * @see #setContentType
187 * @see #getPortletOutputStream
188 */
189
190 public java.io.PrintWriter getWriter() throws java.io.IOException;
191
192
193 /***
194 * Returns the locale assigned to the response.
195 *
196 * @return Locale of this response
197 */
198
199 public java.util.Locale getLocale();
200
201
202 /***
203 * Sets the preferred buffer size for the body of the response.
204 * The portlet container will use a buffer at least as large as
205 * the size requested.
206 * <p>
207 * This method must be called before any response body content is
208 * written; if content has been written, or the portlet container
209 * does not support buffering, this method may throw an
210 * <code>IllegalStateException</code>.
211 *
212 * @param size the preferred buffer size
213 *
214 * @exception java.lang.IllegalStateException
215 * if this method is called after
216 * content has been written, or the
217 * portlet container does not support buffering
218 *
219 * @see #getBufferSize
220 * @see #flushBuffer
221 * @see #isCommitted
222 * @see #reset
223 */
224
225 public void setBufferSize(int size);
226
227
228 /***
229 * Returns the actual buffer size used for the response. If no buffering
230 * is used, this method returns 0.
231 *
232 * @return the actual buffer size used
233 *
234 * @see #setBufferSize
235 * @see #flushBuffer
236 * @see #isCommitted
237 * @see #reset
238 */
239
240 public int getBufferSize();
241
242
243
244 /***
245 * Forces any content in the buffer to be written to the client. A call
246 * to this method automatically commits the response.
247 *
248 * @exception java.io.IOException if an error occured when writing the output
249 *
250 * @see #setBufferSize
251 * @see #getBufferSize
252 * @see #isCommitted
253 * @see #reset
254 */
255
256 public void flushBuffer() throws java.io.IOException;
257
258
259 /***
260 * Clears the content of the underlying buffer in the response without
261 * clearing properties set. If the response has been committed,
262 * this method throws an <code>IllegalStateException</code>.
263 *
264 * @exception IllegalStateException if this method is called after
265 * response is comitted
266 *
267 * @see #setBufferSize
268 * @see #getBufferSize
269 * @see #isCommitted
270 * @see #reset
271 */
272
273 public void resetBuffer();
274
275
276 /***
277 * Returns a boolean indicating if the response has been
278 * committed.
279 *
280 * @return a boolean indicating if the response has been
281 * committed
282 *
283 * @see #setBufferSize
284 * @see #getBufferSize
285 * @see #flushBuffer
286 * @see #reset
287 */
288
289 public boolean isCommitted();
290
291
292 /***
293 * Clears any data that exists in the buffer as well as the properties set.
294 * If the response has been committed, this method throws an
295 * <code>IllegalStateException</code>.
296 *
297 * @exception java.lang.IllegalStateException if the response has already been
298 * committed
299 *
300 * @see #setBufferSize
301 * @see #getBufferSize
302 * @see #flushBuffer
303 * @see #isCommitted
304 */
305
306 public void reset();
307
308
309 /***
310 * Returns a <code>OutputStream</code> suitable for writing binary
311 * data in the response. The portlet container does not encode the
312 * binary data.
313 * <p>
314 * Before calling this method the content type of the
315 * render response must be set using the {@link #setContentType}
316 * method.
317 * <p>
318 * Calling <code>flush()</code> on the OutputStream commits the response.
319 * <p>
320 * Either this method or {@link #getWriter} may be called to write the body, not both.
321 *
322 * @return a <code>OutputStream</code> for writing binary data
323 *
324 * @exception java.lang.IllegalStateException if the <code>getWriter</code> method
325 * has been called on this response, or
326 * if no content type was set using the
327 * <code>setContentType</code> method.
328 *
329 * @exception java.io.IOException if an input or output exception occurred
330 *
331 * @see #setContentType
332 * @see #getWriter
333 */
334
335 public java.io.OutputStream getPortletOutputStream() throws java.io.IOException;
336
337 }
338
339