View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
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