1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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 }