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  /***
26   * The <CODE>PortletURL</CODE> interface represents a URL
27   * that reference the portlet itself.
28   * <p>
29   * A PortletURL is created through the <CODE>RenderResponse</CODE>.
30   * Parameters, a portlet mode, a window state and a security level
31   * can be added to <CODE>PortletURL</CODE> objects. The PortletURL
32   * must be converted to a String in order to embed it into
33   * the markup generated by the portlet.
34   * <P>
35   * There are two types of PortletURLs:
36   * <ul>
37   * <li>Action URLs, they are created with <CODE>RenderResponse.createActionURL</CODE>, and 
38   *     trigger an action request followed by a render request.
39   * <li>Render URLs, they are created with <CODE>RenderResponse.createRenderURL</CODE>, and
40   *     trigger a render request.
41   * </ul>
42   * <p>
43   * The string reprensentation of a PortletURL does not need to be a valid 
44   * URL at the time the portlet is generating its content. It may contain  
45   * special tokens that will be converted to a valid URL, by the portal, 
46   * before the content is returned to the client.
47   */
48  public interface PortletURL
49  {
50  
51  
52  
53  
54    /***
55     * Indicates the window state the portlet should be in, if this 
56     * portlet URL triggers a request.
57     * <p>
58     * A URL can not have more than one window state attached to it.
59     * If more than one window state is set only the last one set
60     * is attached to the URL.
61     * 
62     * @param windowState
63     *               the portlet window state
64     *
65     * @exception WindowStateException
66     *                   if the portlet cannot switch to this state,
67     *                   because the portal does not support this state, the portlet has not 
68     *                   declared in its deployment descriptor that it supports this state, or the current
69     *                   user is not allowed to switch to this state.
70     *                   The <code>PortletRequest.isWindowStateAllowed()</code> method can be used
71     *                   to check if the portlet can set a given window state.
72     * @see PortletRequest#isWindowStateAllowed
73     */
74    public void setWindowState (WindowState windowState)
75      throws WindowStateException;
76  
77  
78    /***
79     * Indicates the portlet mode the portlet must be in, if this
80     * portlet URL triggers a request.
81     * <p>
82     * A URL can not have more than one portlet mode attached to it.
83     * If more than one portlet mode is set only the last one set
84     * is attached to the URL.
85     * 
86     * @param portletMode
87     *               the portlet mode
88     * 
89     * @exception PortletModeException
90     *                   if the portlet cannot switch to this mode,
91     *                   because the portal does not support this mode, the portlet has not
92     *                   declared in its deployment descriptor that it supports this mode for the current markup,
93     *                   or the current user is not allowed to switch to this mode.
94     *                   The <code>PortletRequest.isPortletModeAllowed()</code> method can be used
95     *                   to check if the portlet can set a given portlet mode.
96     * @see PortletRequest#isPortletModeAllowed
97     */
98    public void setPortletMode (PortletMode portletMode)
99      throws PortletModeException;
100 
101 
102   /***
103    * Sets the given String parameter to this URL. 
104    * <p>
105    * This method replaces all parameters with the given key.
106    * <p>
107    * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
108    * all  parameter names and values. Developers should not encode them.
109    * <p>
110    * A portlet container may prefix the attribute names internally 
111    * in order to preserve a unique namespace for the portlet.
112    *
113    * @param   name
114    *          the parameter name
115    * @param   value
116    *          the parameter value
117    *
118    * @exception  java.lang.IllegalArgumentException 
119    *                            if name or value are <code>null</code>.
120    */
121 
122   public void setParameter (String name, String value);
123 
124 
125   /***
126    * Sets the given String array parameter to this URL. 
127    * <p>
128    * This method replaces all parameters with the given key.
129    * <p>
130    * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
131    * all  parameter names and values. Developers should not encode them.
132    * <p>
133    * A portlet container may prefix the attribute names internally 
134    * in order to preserve a unique namespace for the portlet.
135    *
136    * @param   name
137    *          the parameter name
138    * @param   values
139    *          the parameter values
140    *
141    * @exception  java.lang.IllegalArgumentException 
142    *                            if name or values are <code>null</code>.
143    */
144 
145   public void setParameter (String name, String[] values);
146 
147 
148   /***
149    * Sets a parameter map for this URL.
150    * <p>
151    * All previously set parameters are cleared.
152    * <p>
153    * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
154    * all  parameter names and values. Developers should not encode them.
155    * <p>
156    * A portlet container may prefix the attribute names internally, 
157    * in order to preserve a unique namespace for the portlet.
158    *
159    * @param  parameters   Map containing parameter names for 
160    *                      the render phase as 
161    *                      keys and parameter values as map 
162    *                      values. The keys in the parameter
163    *                      map must be of type String. The values 
164    *                      in the parameter map must be of type
165    *                      String array (<code>String[]</code>).
166    *
167    * @exception	java.lang.IllegalArgumentException 
168    *                      if parameters is <code>null</code>, if
169    *                      any of the key/values in the Map are <code>null</code>, 
170    *                      if any of the keys is not a String, or if any of 
171    *                      the values is not a String array.
172    */
173 
174   public void setParameters(java.util.Map parameters);
175 
176 
177   /***
178    * Indicated the security setting for this URL. 
179    * <p>
180    * Secure set to <code>true</code> indicates that the portlet requests
181    * a secure connection between the client and the portlet window for
182    * this URL. Secure set to <code>false</code> indicates that the portlet 
183    * does not need a secure connection for this URL. If the security is not
184    * set for a URL, it will stay the same as the current request. 
185    *
186    * @param  secure  true, if portlet requests to have a secure connection
187    *                 between its portlet window and the client; false, if
188    *                 the portlet does not require a secure connection.
189    *
190    * @throws PortletSecurityException  if the run-time environment does
191    *                                   not support the indicated setting
192    */
193 
194   public void setSecure (boolean secure) throws PortletSecurityException;
195 
196 
197   /***
198    * Returns the portlet URL string representation to be embedded in the
199    * markup.<br>
200    * Note that the returned String may not be a valid URL, as it may
201    * be rewritten by the portal/portlet-container before returning the 
202    * markup to the client.
203    *
204    * @return   the encoded URL as a string
205    */
206 
207   public String toString ();
208 }