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
041: * the portlet window state
042: *
043: * @exception WindowStateException
044: * if the portlet cannot switch to this state,
045: * because the portal does not support this state, the portlet has not
046: * declared in its deployment descriptor that it supports this state, or the current
047: * user is not allowed to switch to this state.
048: * The <code>PortletRequest.isWindowStateAllowed()</code> method can be used
049: * to check if the portlet can set a given window state.
050: * @see PortletRequest#isWindowStateAllowed
051: */
052: public void setWindowState(WindowState windowState)
053: throws WindowStateException;
054:
055: /**
056: * Indicates the portlet mode the portlet must be in, if this
057: * portlet URL triggers a request.
058: * <p>
059: * A URL can not have more than one portlet mode attached to it.
060: * If more than one portlet mode is set only the last one set
061: * is attached to the URL.
062: *
063: * @param portletMode
064: * the portlet mode
065: *
066: * @exception PortletModeException
067: * if the portlet cannot switch to this mode,
068: * because the portal does not support this mode, the portlet has not
069: * declared in its deployment descriptor that it supports this mode for the current markup,
070: * or the current user is not allowed to switch to this mode.
071: * The <code>PortletRequest.isPortletModeAllowed()</code> method can be used
072: * to check if the portlet can set a given portlet mode.
073: * @see PortletRequest#isPortletModeAllowed
074: */
075: public void setPortletMode(PortletMode portletMode)
076: throws PortletModeException;
077:
078: /**
079: * Sets the given String parameter to this URL.
080: * <p>
081: * This method replaces all parameters with the given key.
082: * <p>
083: * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
084: * all parameter names and values. Developers should not encode them.
085: * <p>
086: * A portlet container may prefix the attribute names internally
087: * in order to preserve a unique namespace for the portlet.
088: *
089: * @param name
090: * the parameter name
091: * @param value
092: * the parameter value
093: *
094: * @exception java.lang.IllegalArgumentException
095: * if name or value are <code>null</code>.
096: */
097:
098: public void setParameter(String name, String value);
099:
100: /**
101: * Sets the given String array parameter to this URL.
102: * <p>
103: * This method replaces all parameters with the given key.
104: * <p>
105: * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
106: * all parameter names and values. Developers should not encode them.
107: * <p>
108: * A portlet container may prefix the attribute names internally
109: * in order to preserve a unique namespace for the portlet.
110: *
111: * @param name
112: * the parameter name
113: * @param values
114: * the parameter values
115: *
116: * @exception java.lang.IllegalArgumentException
117: * if name or values are <code>null</code>.
118: */
119:
120: public void setParameter(String name, String[] values);
121:
122: /**
123: * Sets a parameter map for this URL.
124: * <p>
125: * All previously set parameters are cleared.
126: * <p>
127: * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
128: * all parameter names and values. Developers should not encode them.
129: * <p>
130: * A portlet container may prefix the attribute names internally,
131: * in order to preserve a unique namespace for the portlet.
132: *
133: * @param parameters Map containing parameter names for
134: * the render phase as
135: * keys and parameter values as map
136: * values. The keys in the parameter
137: * map must be of type String. The values
138: * in the parameter map must be of type
139: * String array (<code>String[]</code>).
140: *
141: * @exception java.lang.IllegalArgumentException
142: * if parameters is <code>null</code>, if
143: * any of the key/values in the Map are <code>null</code>,
144: * if any of the keys is not a String, or if any of
145: * the values is not a String array.
146: */
147:
148: public void setParameters(java.util.Map parameters);
149:
150: /**
151: * Indicated the security setting for this URL.
152: * <p>
153: * Secure set to <code>true</code> indicates that the portlet requests
154: * a secure connection between the client and the portlet window for
155: * this URL. Secure set to <code>false</code> indicates that the portlet
156: * does not need a secure connection for this URL. If the security is not
157: * set for a URL, it will stay the same as the current request.
158: *
159: * @param secure true, if portlet requests to have a secure connection
160: * between its portlet window and the client; false, if
161: * the portlet does not require a secure connection.
162: *
163: * @throws PortletSecurityException if the run-time environment does
164: * not support the indicated setting
165: */
166:
167: public void setSecure(boolean secure)
168: throws PortletSecurityException;
169:
170: /**
171: * Returns the portlet URL string representation to be embedded in the
172: * markup.<br>
173: * Note that the returned String may not be a valid URL, as it may
174: * be rewritten by the portal/portlet-container before returning the
175: * markup to the client.
176: *
177: * @return the encoded URL as a string
178: */
179:
180: public String toString();
181: }
|