PortletURL


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