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