001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>RenderResponse</CODE> defines an object to assist a portlet in
009: * sending a response to the portal.
010: * It extends the <CODE>PortletResponse</CODE> interface to provide specific
011: * render response functionality to portlets.<br>
012: * The portlet container creates a <CODE>RenderResponse</CODE> object and
013: * passes it as argument to the portlet's <CODE>render</CODE> method.
014: *
015: * @see RenderRequest
016: * @see PortletResponse
017: */
018: public interface RenderResponse extends PortletResponse {
019:
020: /**
021: * Property to set the expiration time in seconds for this
022: * response using the <code>setProperty</code> method.
023: * <P>
024: * If the expiration value is set to 0, caching is disabled
025: * for this portlet; if the value is set to -1,
026: * the cache does not expire.
027: * <p>
028: * The value is <code>"portlet.expiration-cache"</code>.
029: */
030: public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
031:
032: /**
033: * Returns the MIME type that can be used to contribute
034: * markup to the render response.
035: * <p>
036: * If no content type was set previously using the {@link #setContentType} method
037: * this method retuns <code>null</code>.
038: *
039: * @see #setContentType
040: *
041: * @return the MIME type of the response, or <code>null</code>
042: * if no content type is set
043: */
044:
045: public String getContentType();
046:
047: /**
048: * Creates a portlet URL targeting the portlet. If no portlet mode,
049: * window state or security modifier is set in the PortletURL the
050: * current values are preserved. If a request is triggered by the
051: * PortletURL, it results in a render request.
052: * <p>
053: * The returned URL can be further extended by adding
054: * portlet-specific parameters and portlet modes and window states.
055: * <p>
056: * The created URL will per default not contain any parameters
057: * of the current render request.
058: *
059: * @return a portlet render URL
060: */
061: public PortletURL createRenderURL();
062:
063: /**
064: * Creates a portlet URL targeting the portlet. If no portlet mode,
065: * window state or security modifier is set in the PortletURL the
066: * current values are preserved. If a request is triggered by the
067: * PortletURL, it results in an action request.
068: * <p>
069: * The returned URL can be further extended by adding
070: * portlet-specific parameters and portlet modes and window states.
071: * <p>
072: * The created URL will per default not contain any parameters
073: * of the current render request.
074: *
075: * @return a portlet action URL
076: */
077: public PortletURL createActionURL();
078:
079: /**
080: * The value returned by this method should be prefixed or appended to
081: * elements, such as JavaScript variables or function names, to ensure
082: * they are unique in the context of the portal page.
083: *
084: * @return the namespace
085: */
086:
087: public String getNamespace();
088:
089: /**
090: * This method sets the title of the portlet.
091: * <p>
092: * The value can be a text String
093: *
094: * @param title portlet title as text String or resource URI
095: */
096:
097: public void setTitle(String title);
098:
099: /**
100: * Sets the MIME type for the render response. The portlet must
101: * set the content type before calling {@link #getWriter} or
102: * {@link #getPortletOutputStream}.
103: * <p>
104: * Calling <code>setContentType</code> after <code>getWriter</code>
105: * or <code>getOutputStream</code> does not change the content type.
106: *
107: * @param type the content MIME type
108: *
109: * @throws java.lang.IllegalArgumentException
110: * if the given type is not in the list returned
111: * by <code>PortletRequest.getResponseContentTypes</code>
112: *
113: * @see RenderRequest#getResponseContentTypes
114: * @see #getContentType
115: */
116:
117: public void setContentType(String type);
118:
119: /**
120: * Returns the name of the charset used for
121: * the MIME body sent in this response.
122: *
123: * <p>See <a href="http://ds.internic.net/rfc/rfc2045.txt">RFC 2047</a>
124: * for more information about character encoding and MIME.
125: *
126: * @return a <code>String</code> specifying the
127: * name of the charset, for
128: * example, <code>ISO-8859-1</code>
129: *
130: */
131:
132: public String getCharacterEncoding();
133:
134: /**
135: * Returns a PrintWriter object that can send character
136: * text to the portal.
137: * <p>
138: * Before calling this method the content type of the
139: * render response must be set using the {@link #setContentType}
140: * method.
141: * <p>
142: * Either this method or {@link #getPortletOutputStream} may be
143: * called to write the body, not both.
144: *
145: * @return a <code>PrintWriter</code> object that
146: * can return character data to the portal
147: *
148: * @exception java.io.IOException
149: * if an input or output exception occurred
150: * @exception java.lang.IllegalStateException
151: * if the <code>getPortletOutputStream</code> method
152: * has been called on this response,
153: * or if no content type was set using the
154: * <code>setContentType</code> method.
155: *
156: * @see #setContentType
157: * @see #getPortletOutputStream
158: */
159:
160: public java.io.PrintWriter getWriter() throws java.io.IOException;
161:
162: /**
163: * Returns the locale assigned to the response.
164: *
165: * @return Locale of this response
166: */
167:
168: public java.util.Locale getLocale();
169:
170: /**
171: * Sets the preferred buffer size for the body of the response.
172: * The portlet container will use a buffer at least as large as
173: * the size requested.
174: * <p>
175: * This method must be called before any response body content is
176: * written; if content has been written, or the portlet container
177: * does not support buffering, this method may throw an
178: * <code>IllegalStateException</code>.
179: *
180: * @param size the preferred buffer size
181: *
182: * @exception java.lang.IllegalStateException
183: * if this method is called after
184: * content has been written, or the
185: * portlet container does not support buffering
186: *
187: * @see #getBufferSize
188: * @see #flushBuffer
189: * @see #isCommitted
190: * @see #reset
191: */
192:
193: public void setBufferSize(int size);
194:
195: /**
196: * Returns the actual buffer size used for the response. If no buffering
197: * is used, this method returns 0.
198: *
199: * @return the actual buffer size used
200: *
201: * @see #setBufferSize
202: * @see #flushBuffer
203: * @see #isCommitted
204: * @see #reset
205: */
206:
207: public int getBufferSize();
208:
209: /**
210: * Forces any content in the buffer to be written to the client. A call
211: * to this method automatically commits the response.
212: *
213: * @exception java.io.IOException if an error occured when writing the output
214: *
215: * @see #setBufferSize
216: * @see #getBufferSize
217: * @see #isCommitted
218: * @see #reset
219: */
220:
221: public void flushBuffer() throws java.io.IOException;
222:
223: /**
224: * Clears the content of the underlying buffer in the response without
225: * clearing properties set. If the response has been committed,
226: * this method throws an <code>IllegalStateException</code>.
227: *
228: * @exception IllegalStateException if this method is called after
229: * response is comitted
230: *
231: * @see #setBufferSize
232: * @see #getBufferSize
233: * @see #isCommitted
234: * @see #reset
235: */
236:
237: public void resetBuffer();
238:
239: /**
240: * Returns a boolean indicating if the response has been
241: * committed.
242: *
243: * @return a boolean indicating if the response has been
244: * committed
245: *
246: * @see #setBufferSize
247: * @see #getBufferSize
248: * @see #flushBuffer
249: * @see #reset
250: */
251:
252: public boolean isCommitted();
253:
254: /**
255: * Clears any data that exists in the buffer as well as the properties set.
256: * If the response has been committed, this method throws an
257: * <code>IllegalStateException</code>.
258: *
259: * @exception java.lang.IllegalStateException if the response has already been
260: * committed
261: *
262: * @see #setBufferSize
263: * @see #getBufferSize
264: * @see #flushBuffer
265: * @see #isCommitted
266: */
267:
268: public void reset();
269:
270: /**
271: * Returns a <code>OutputStream</code> suitable for writing binary
272: * data in the response. The portlet container does not encode the
273: * binary data.
274: * <p>
275: * Before calling this method the content type of the
276: * render response must be set using the {@link #setContentType}
277: * method.
278: * <p>
279: * Calling <code>flush()</code> on the OutputStream commits the response.
280: * <p>
281: * Either this method or {@link #getWriter} may be called to write the body, not both.
282: *
283: * @return a <code>OutputStream</code> for writing binary data
284: *
285: * @exception java.lang.IllegalStateException if the <code>getWriter</code> method
286: * has been called on this response, or
287: * if no content type was set using the
288: * <code>setContentType</code> method.
289: *
290: * @exception java.io.IOException if an input or output exception occurred
291: *
292: * @see #setContentType
293: * @see #getWriter
294: */
295:
296: public java.io.OutputStream getPortletOutputStream()
297: throws java.io.IOException;
298:
299: }
|