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>ActionResponse</CODE> interface represents the portlet
26   * response to an action request.
27   * It extends the <CODE>PortletResponse</CODE> interface to provide specific 
28   * action response functionality to portlets.<br>
29   * The portlet container creates an <CODE>ActionResponse</CODE> object and 
30   * passes it as argument to the portlet's <CODE>processAction</CODE> method.
31   * 
32   * @see ActionRequest
33   * @see PortletResponse
34   */
35  public interface ActionResponse extends PortletResponse
36  {
37  
38  
39    /***
40     * Sets the window state of a portlet to the given window state.
41     * <p>
42     * Possible values are the standard window states and any custom 
43     * window states supported by the portal and the portlet. 
44     * Standard window states are:
45     * <ul>
46     * <li>MINIMIZED
47     * <li>NORMAL
48     * <li>MAXIMIZED
49     * </ul>
50     *
51     * @param windowState
52     *               the new portlet window state
53     *
54     * @exception WindowStateException
55     *                   if the portlet cannot switch to the specified window state.
56     *                   To avoid this exception the portlet can check the allowed
57     *                   window states with <code>Request.isWindowStateAllowed()</code>.
58     * @exception java.lang.IllegalStateException
59     *                    if the method is invoked after <code>sendRedirect</code> has been called.
60     *
61     * @see WindowState
62     */
63  
64    public void setWindowState (WindowState windowState) 
65      throws WindowStateException;
66  
67  
68    /***
69     * Sets the portlet mode of a portlet to the given portlet mode.
70     * <p>
71     * Possible values are the standard portlet modes and any custom 
72     * portlet modes supported by the portal and the portlet. Portlets 
73     * must declare in the deployment descriptor the portlet modes they 
74     * support for each markup type.  
75     * Standard portlet modes are:
76     * <ul>
77     * <li>EDIT
78     * <li>HELP
79     * <li>VIEW
80     * </ul>
81     * <p>
82     * Note: The portlet may still be called in a different window
83     *       state in the next render call, depending on the portlet container / portal.
84     * 
85     * @param portletMode
86     *               the new portlet mode
87     *
88     * @exception PortletModeException
89     *                   if the portlet cannot switch to this portlet mode,
90     *                   because the portlet or portal does not support it for this markup,
91     *                   or the current user is not allowed to switch to this portlet mode.
92     *                   To avoid this exception the portlet can check the allowed
93     *                   portlet modes with <code>Request.isPortletModeAllowed()</code>.
94     * @exception java.lang.IllegalStateException
95     *                    if the method is invoked after <code>sendRedirect</code> has been called.
96     */
97  
98    public void setPortletMode (PortletMode portletMode)
99      throws PortletModeException;
100 
101 
102   /***
103    * Instructs the portlet container to send a redirect response 
104    * to the client using the specified redirect location URL.  
105    * <p>
106    * This method only accepts an absolute URL (e.g. 
107    * <code>http://my.co/myportal/mywebap/myfolder/myresource.gif</code>)
108    * or a full path URI (e.g. <code>/myportal/mywebap/myfolder/myresource.gif</code>).
109    * If required, 
110    * the portlet container may encode the given URL before the 
111    * redirection is issued to the client.
112    * <p>
113    * The sendRedirect method can not be invoked after any of the 
114    * following methods of the ActionResponse interface has been called:
115    * <ul>
116    * <li>setPortletMode
117    * <li>setWindowState
118    * <li>setRenderParameter
119    * <li>setRenderParameters
120    * </ul>
121    *
122    * @param		location	the redirect location URL
123    *
124    * @exception	java.io.IOException	
125    *                    if an input or output exception occurs.
126    * @exception	java.lang.IllegalArgumentException	
127    *                    if a relative path URL is given
128    * @exception java.lang.IllegalStateException
129    *                    if the method is invoked after any of above mentioned methods of 
130    *                    the ActionResponse interface has been called.
131    */
132 
133   public void sendRedirect(String location)
134     throws java.io.IOException; 
135 
136 
137   /***
138    * Sets a parameter map for the render request.
139    * <p>
140    * All previously set render parameters are cleared.
141    * <p>
142    * These parameters will be accessible in all
143    * sub-sequent render calls via the
144    * <code>PortletRequest.getParameter</code> call until
145    * a new request is targeted to the portlet.
146    * <p>
147    * The given parameters do not need to be encoded
148    * prior to calling this method.
149    *
150    * @param  parameters   Map containing parameter names for 
151    *                      the render phase as 
152    *                      keys and parameter values as map 
153    *                      values. The keys in the parameter
154    *                      map must be of type String. The values 
155    *                      in the parameter map must be of type
156    *                      String array (<code>String[]</code>).
157    *
158    * @exception	java.lang.IllegalArgumentException 
159    *                      if parameters is <code>null</code>, if
160    *                      any of the key/values in the Map are <code>null</code>, 
161    *                      if any of the keys is not a String, or if any of 
162    *                      the values is not a String array.
163    * @exception java.lang.IllegalStateException
164    *                    if the method is invoked after <code>sendRedirect</code> has been called.
165    */
166 
167   public void setRenderParameters(java.util.Map parameters);
168 
169 
170   /***
171    * Sets a String parameter for the render request.
172    * <p>
173    * These parameters will be accessible in all
174    * sub-sequent render calls via the
175    * <code>PortletRequest.getParameter</code> call until
176    * a request is targeted to the portlet.
177    * <p>
178    * This method replaces all parameters with the given key.
179    * <p>
180    * The given parameter do not need to be encoded
181    * prior to calling this method.
182    *
183    * @param  key    key of the render parameter
184    * @param  value  value of the render parameter
185    *
186    * @exception	java.lang.IllegalArgumentException	
187    *                      if key or value are <code>null</code>.
188    * @exception java.lang.IllegalStateException
189    *                    if the method is invoked after <code>sendRedirect</code> has been called.
190    */
191 
192   public void setRenderParameter(String key, String value);
193 
194 
195   /***
196    * Sets a String array parameter for the render request.
197    * <p>
198    * These parameters will be accessible in all
199    * sub-sequent render calls via the
200    * <code>PortletRequest.getParameter</code> call until
201    * a request is targeted to the portlet.
202    * <p>
203    * This method replaces all parameters with the given key.
204    * <p>
205    * The given parameter do not need to be encoded
206    * prior to calling this method.
207    * 
208    * @param  key     key of the render parameter
209    * @param  values  values of the render parameter
210    *
211    * @exception	java.lang.IllegalArgumentException	
212    *                      if key or value are <code>null</code>.
213    * @exception java.lang.IllegalStateException
214    *                    if the method is invoked after <code>sendRedirect</code> has been called.
215    */
216 
217   public void setRenderParameter(String key, String[] values);
218 
219 
220 }
221 
222