001    /**
002     * Copyright (c) 2000-2011 Liferay, Inc. All rights reserved.
003     *
004     * The contents of this file are subject to the terms of the Liferay Enterprise
005     * Subscription License ("License"). You may not use this file except in
006     * compliance with the License. You can obtain a copy of the License by
007     * contacting Liferay, Inc. See the License for the specific language governing
008     * permissions and limitations under the License, including but not limited to
009     * distribution rights of the Software.
010     *
011     *
012     *
013     */
014    
015    package com.liferay.portal.kernel.portlet;
016    
017    import java.io.Serializable;
018    
019    import java.util.Map;
020    import java.util.Set;
021    
022    import javax.portlet.PortletURL;
023    import javax.portlet.ResourceURL;
024    
025    /**
026     * Represents a URL pointing to a portlet.
027     *
028     * @author Brian Wing Shun Chan
029     * @see    com.liferay.portlet.PortletURLImpl
030     */
031    public interface LiferayPortletURL
032            extends PortletURL, ResourceURL, Serializable {
033    
034            /**
035             * Adds a parameter that is included in the friendly URL path and does not
036             * need to appear in the query string.
037             *
038             * @param name the name of the parameter that is included in the path
039             */
040            public void addParameterIncludedInPath(String name);
041    
042            /**
043             * Gets the lifecycle of the portlet this URL points to.
044             *
045             * @return the portlet lifecycle
046             * @see    #setLifecycle(String)
047             */
048            public String getLifecycle();
049    
050            /**
051             * Gets the first value of the URL parameter.
052             *
053             * @param  name the name of the URL parameter to get the value of
054             * @return the first value of the URL parameter
055             */
056            public String getParameter(String name);
057    
058            /**
059             * Gets the ID of the portlet this URL points to.
060             *
061             * @return the ID of the portlet this URL points to
062             */
063            public String getPortletId();
064    
065            /**
066             * Gets the map of reserved parameters for this URL.
067             *
068             * <p>
069             * This method is only used internally. Reserved parameters contain special,
070             * Liferay specific information, such as <code>p_p_id</code> and
071             * <code>p_p_lifecycle</code>.
072             * </p>
073             *
074             * @return the reserved parameter names and values in a read-only map
075             */
076            public Map<String, String> getReservedParameterMap();
077    
078            /**
079             * Gets the ID of the resource this URL points to.
080             *
081             * @return the ID of the resource this URL points to
082             */
083            public String getResourceID();
084    
085            /**
086             * Determines if this URL is an anchor pointing to the specified portlet on
087             * the page.
088             *
089             * @return whether this URL is an anchor pointing to the specified portlet
090             *         on the page
091             * @see    #setAnchor(boolean)
092             */
093            public boolean isAnchor();
094    
095            /**
096             * Determines if the render parameters in the current request should be
097             * copied to this URL.
098             *
099             * @return whether the render parameters in the current request should be
100             *         copied to this URL
101             * @see    #setCopyCurrentRenderParameters(boolean)
102             */
103            public boolean isCopyCurrentRenderParameters();
104    
105            /**
106             * Determines if this URL should be encrypted.
107             *
108             * @return <code>true</code> if this URL should be encrypted;
109             *         <code>false</code> otherwise
110             * @see    #setEncrypt(boolean)
111             */
112            public boolean isEncrypt();
113    
114            /**
115             * Determines if this URL should be XML escaped.
116             *
117             * @return <code>true</code> if this URL should be XML escaped;
118             *         <code>false</code> otherwise
119             * @see    #setEscapeXml(boolean)
120             */
121            public boolean isEscapeXml();
122    
123            /**
124             * Determines if the parameter is included in the friendly URL path.
125             *
126             * @param  name the name of the parameter to check for inclusion in the path
127             * @return whether the parameter is included in the friendly URL path
128             * @see    #addParameterIncludedInPath(String)
129             */
130            public boolean isParameterIncludedInPath(String name);
131    
132            /**
133             * Determines if this URL is secure (https).
134             *
135             * @return <code>true</code> if this URL is secure; <code>false</code>
136             *         otherwise
137             */
138            public boolean isSecure();
139    
140            /**
141             * Sets the lifecycle of the portlet this URL points to.
142             *
143             * <p>
144             * Valid lifecycles are:
145             * </p>
146             *
147             * <ul>
148             * <li>
149             * {@link javax.portlet.PortletRequest#ACTION_PHASE}
150             * </li>
151             * <li>
152             * {@link javax.portlet.PortletRequest#RENDER_PHASE}
153             * </li>
154             * <li>
155             * {@link javax.portlet.PortletRequest#RESOURCE_PHASE}
156             * </li>
157             * </ul>
158             *
159             * @param lifecycle the lifecycle of the portlet this URL points to
160             */
161            public void setLifecycle(String lifecycle);
162    
163            /**
164             * Sets the URL parameter to the value.
165             *
166             * @param name the name of the URL parameter
167             * @param value the value of the URL parameter
168             * @param append whether the new value should be appended to any existing
169             *        values for the parameter. If <code>append</code> is
170             *        <code>false</code> any existing values will be overwritten with
171             *        the new value.
172             */
173            public void setParameter(String name, String value, boolean append);
174    
175            /**
176             * Sets the URL parameter the values.
177             *
178             * @param name the name of the URL parameter
179             * @param append whether the new values should be appended to any existing
180             *        values for the parameter. If <code>append</code> is
181             *        <code>false</code> any existing values will be overwritten with
182             *        the new values.
183             */
184            public void setParameter(String name, String[] values, boolean append);
185    
186            public Set<String> getParametersIncludedInPath();
187    
188            /**
189             * Sets whether this URL is an anchor pointing to the specified portlet on
190             * the page.
191             *
192             * <p>
193             * An anchor URL will cause the user's browser to automatically jump down to
194             * the specified portlet after the page loads, avoiding the need to scroll.
195             * </p>
196             *
197             * @param anchor whether this URL is an anchor pointing to the specified
198             *        portlet on the page
199             */
200            public void setAnchor(boolean anchor);
201    
202            /**
203             * Sets whether the render parameters in the current request should be
204             * copied to this URL.
205             *
206             * <p>
207             * New parameters set on this URL will appear before the copied render
208             * parameters.
209             * </p>
210             *
211             * @param copyCurrentRenderParameters whether the render parameters in the
212             *        current request should be copied to this URL
213             */
214            public void setCopyCurrentRenderParameters(
215                    boolean copyCurrentRenderParameters);
216    
217            public void setDoAsGroupId(long doAsGroupId);
218    
219            /**
220             * Sets the ID of the user to impersonate.
221             *
222             * <p>
223             * When a page is accessed while impersonating a user, it will appear
224             * exactly as it would to that user.
225             * </p>
226             *
227             * @param doAsUserId the ID of the user to impersonate in the portlet this
228             *        URL points to
229             */
230            public void setDoAsUserId(long doAsUserId);
231    
232            public void setDoAsUserLanguageId(String doAsUserLanguageId);
233    
234            /**
235             * Sets whether this URL should be encrypted.
236             *
237             * <p>
238             * In an encrypted URL, the value of every parameter will be encrypted using
239             * the company's key. This allows sensitive information to be placed in the
240             * URL without being vulnerable to snooping.
241             * </p>
242             *
243             * <p>
244             * Note that this is not the same as making a URL {@link #setSecure(boolean)
245             * secure}.
246             * </p>
247             */
248            public void setEncrypt(boolean encrypt);
249    
250            /**
251             * Sets whether this URL should be XML escaped.
252             *
253             * <p>
254             * If a URL is XML escaped, it will automatically have special characters
255             * escaped when it is converted to a string or written to a {@link
256             * java.io.Writer}.
257             * </p>
258             *
259             * @param escapeXml whether this URL should be XML escaped
260             */
261            public void setEscapeXml(boolean escapeXml);
262    
263            /**
264             * Sets the portlet layout ID.
265             *
266             * @param plid the portlet layout ID
267             */
268            public void setPlid(long plid);
269    
270            /**
271             * Sets the ID of the target portlet.
272             */
273            public void setPortletId(String portletId);
274    
275    }