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>PortletURL</CODE> interface represents a URL
009: * that reference the portlet itself.
010: * <p/>
011: * A PortletURL is created through the <CODE>RenderResponse</CODE>.
012: * Parameters, a portlet mode, a window state and a security level
013: * can be added to <CODE>PortletURL</CODE> objects. The PortletURL
014: * must be converted to a String in order to embed it into
015: * the markup generated by the portlet.
016: * <P>
017: * There are two types of PortletURLs:
018: * <ul>
019: * <li>Action URLs, they are created with <CODE>RenderResponse.createActionURL</CODE>, and
020: * trigger an action request followed by a render request.
021: * <li>Render URLs, they are created with <CODE>RenderResponse.createRenderURL</CODE>, and
022: * trigger a render request.
023: * </ul>
024: * <p/>
025: * The string reprensentation of a PortletURL does not need to be a valid
026: * URL at the time the portlet is generating its content. It may contain
027: * special tokens that will be converted to a valid URL, by the portal,
028: * before the content is returned to the client.
029: */
030: public interface PortletURL {
031:
032: /**
033: * Indicates the window state the portlet should be in, if this
034: * portlet URL triggers a request.
035: * <p/>
036: * A URL can not have more than one window state attached to it.
037: * If more than one window state is set only the last one set
038: * is attached to the URL.
039: *
040: * @param windowState the portlet window state
041: * @throws WindowStateException if the portlet cannot switch to this state,
042: * because the portal does not support this state, the portlet has not
043: * declared in its deployment descriptor that it supports this state, or the current
044: * user is not allowed to switch to this state.
045: * The <code>PortletRequest.isWindowStateAllowed()</code> method can be used
046: * to check if the portlet can set a given window state.
047: * @see PortletRequest#isWindowStateAllowed
048: */
049: public void setWindowState(WindowState windowState)
050: throws WindowStateException;
051:
052: /**
053: * Indicates the portlet mode the portlet must be in, if this
054: * portlet URL triggers a request.
055: * <p/>
056: * A URL can not have more than one portlet mode attached to it.
057: * If more than one portlet mode is set only the last one set
058: * is attached to the URL.
059: *
060: * @param portletMode the portlet mode
061: * @throws PortletModeException if the portlet cannot switch to this mode,
062: * because the portal does not support this mode, the portlet has not
063: * declared in its deployment descriptor that it supports this mode for the current markup,
064: * or the current user is not allowed to switch to this mode.
065: * The <code>PortletRequest.isPortletModeAllowed()</code> method can be used
066: * to check if the portlet can set a given portlet mode.
067: * @see PortletRequest#isPortletModeAllowed
068: */
069: public void setPortletMode(PortletMode portletMode)
070: throws PortletModeException;
071:
072: /**
073: * Sets the given String parameter to this URL.
074: * <p/>
075: * This method replaces all parameters with the given key.
076: * <p/>
077: * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
078: * all parameter names and values. Developers should not encode them.
079: * <p/>
080: * A portlet container may prefix the attribute names internally
081: * in order to preserve a unique namespace for the portlet.
082: *
083: * @param name the parameter name
084: * @param value the parameter value
085: * @throws java.lang.IllegalArgumentException
086: * if name or value are <code>null</code>.
087: */
088:
089: public void setParameter(String name, String value);
090:
091: /**
092: * Sets the given String array parameter to this URL.
093: * <p/>
094: * This method replaces all parameters with the given key.
095: * <p/>
096: * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
097: * all parameter names and values. Developers should not encode them.
098: * <p/>
099: * A portlet container may prefix the attribute names internally
100: * in order to preserve a unique namespace for the portlet.
101: *
102: * @param name the parameter name
103: * @param values the parameter values
104: * @throws java.lang.IllegalArgumentException
105: * if name or values are <code>null</code>.
106: */
107:
108: public void setParameter(String name, String[] values);
109:
110: /**
111: * Sets a parameter map for this URL.
112: * <p/>
113: * All previously set parameters are cleared.
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 parameters Map containing parameter names for
122: * the render phase as
123: * keys and parameter values as map
124: * values. The keys in the parameter
125: * map must be of type String. The values
126: * in the parameter map must be of type
127: * String array (<code>String[]</code>).
128: * @exception java.lang.IllegalArgumentException if parameters is <code>null</code>, if
129: * any of the key/values in the Map are <code>null</code>,
130: * if any of the keys is not a String, or if any of
131: * the values is not a String array.
132: */
133:
134: public void setParameters(java.util.Map parameters);
135:
136: /**
137: * Indicated the security setting for this URL.
138: * <p/>
139: * Secure set to <code>true</code> indicates that the portlet requests
140: * a secure connection between the client and the portlet window for
141: * this URL. Secure set to <code>false</code> indicates that the portlet
142: * does not need a secure connection for this URL. If the security is not
143: * set for a URL, it will stay the same as the current request.
144: *
145: * @param secure true, if portlet requests to have a secure connection
146: * between its portlet window and the client; false, if
147: * the portlet does not require a secure connection.
148: * @throws PortletSecurityException if the run-time environment does
149: * not support the indicated setting
150: */
151:
152: public void setSecure(boolean secure)
153: throws PortletSecurityException;
154:
155: /**
156: * Returns the portlet URL string representation to be embedded in the
157: * markup.<br>
158: * Note that the returned String may not be a valid URL, as it may
159: * be rewritten by the portal/portlet-container before returning the
160: * markup to the client.
161: *
162: * @return the encoded URL as a string
163: */
164:
165: public String toString();
166: }
|