RenderResponse


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