001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
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
039             */
040            public void addParameterIncludedInPath(String name);
041    
042            /**
043             * Returns the portlet lifecycle of this URL's target portlet.
044             *
045             * @return the portlet lifecycle of this URL's target portlet
046             * @see    #setLifecycle(String)
047             */
048            public String getLifecycle();
049    
050            /**
051             * Returns the first value of the URL parameter.
052             *
053             * @param  name the name of the URL parameter
054             * @return the first value of the URL parameter
055             */
056            public String getParameter(String name);
057    
058            /**
059             * Returns the parameters that are included in the friendly URL path and do
060             * not need to appear in the query string.
061             *
062             * @return the names of the parameters that are included in the friendly URL
063             *         path and do not need to appear in the query string
064             */
065            public Set<String> getParametersIncludedInPath();
066    
067            /**
068             * Returns the ID of this URL's target portlet.
069             *
070             * @return the ID of this URL's target portlet
071             */
072            public String getPortletId();
073    
074            public Set<String> getRemovedParameterNames();
075    
076            /**
077             * Returns the map of reserved parameters for this URL.
078             *
079             * <p>
080             * This method is only used internally. Reserved parameters contain special,
081             * Liferay specific information, such as <code>p_p_id</code> and
082             * <code>p_p_lifecycle</code>.
083             * </p>
084             *
085             * @return the reserved parameter names and values in a read-only map
086             */
087            public Map<String, String> getReservedParameterMap();
088    
089            /**
090             * Returns the ID of this URL's target resource.
091             *
092             * @return the ID of this URL's target resource
093             */
094            public String getResourceID();
095    
096            /**
097             * Returns <code>true</code> if this URL is an anchor pointing to the
098             * specified portlet on the page.
099             *
100             * @return whether this URL is an anchor pointing to the specified portlet
101             *         on the page
102             * @see    #setAnchor(boolean)
103             */
104            public boolean isAnchor();
105    
106            /**
107             * Returns <code>true</code> if the render parameters in the current request
108             * should be copied to this URL.
109             *
110             * @return whether the render parameters in the current request should be
111             *         copied to this URL
112             * @see    #setCopyCurrentRenderParameters(boolean)
113             */
114            public boolean isCopyCurrentRenderParameters();
115    
116            /**
117             * Returns <code>true</code> if this URL should be encrypted.
118             *
119             * @return <code>true</code> if this URL should be encrypted;
120             *         <code>false</code> otherwise
121             * @see    #setEncrypt(boolean)
122             */
123            public boolean isEncrypt();
124    
125            /**
126             * Returns <code>true</code> if this URL should be XML escaped.
127             *
128             * @return <code>true</code> if this URL should be XML escaped;
129             *         <code>false</code> otherwise
130             * @see    #setEscapeXml(boolean)
131             */
132            public boolean isEscapeXml();
133    
134            /**
135             * Returns <code>true</code> if the parameter is included in the friendly
136             * URL path.
137             *
138             * @param  name the name of the parameter to check for inclusion in the path
139             * @return whether the parameter is included in the friendly URL path
140             * @see    #addParameterIncludedInPath(String)
141             */
142            public boolean isParameterIncludedInPath(String name);
143    
144            /**
145             * Returns <code>true</code> if this URL is secure (https).
146             *
147             * @return <code>true</code> if this URL is secure; <code>false</code>
148             *         otherwise
149             */
150            public boolean isSecure();
151    
152            /**
153             * Sets whether this URL is an anchor pointing to the specified portlet on
154             * the page.
155             *
156             * <p>
157             * An anchor URL will cause the user's browser to automatically jump down to
158             * the specified portlet after the page loads, avoiding the need to scroll.
159             * </p>
160             *
161             * @param anchor whether this URL is an anchor pointing to the specified
162             *        portlet on the page
163             */
164            public void setAnchor(boolean anchor);
165    
166            /**
167             * Sets whether the render parameters in the current request should be
168             * copied to this URL.
169             *
170             * <p>
171             * New parameters set on this URL will appear before the copied render
172             * parameters.
173             * </p>
174             *
175             * @param copyCurrentRenderParameters whether the render parameters in the
176             *        current request should be copied to this URL
177             */
178            public void setCopyCurrentRenderParameters(
179                    boolean copyCurrentRenderParameters);
180    
181            public void setDoAsGroupId(long doAsGroupId);
182    
183            /**
184             * Sets the ID of the user to impersonate.
185             *
186             * <p>
187             * When a page is accessed while impersonating a user, it will appear
188             * exactly as it would to that user.
189             * </p>
190             *
191             * @param doAsUserId the ID of the user to impersonate in the portlet this
192             *        URL points to
193             */
194            public void setDoAsUserId(long doAsUserId);
195    
196            /**
197             * Sets the language ID of the user to impersonate. This will only have an
198             * effect when a user is being impersonated via {@link
199             * #setDoAsUserId(long)}.
200             *
201             * <p>
202             * The language set here will override the impersonated user's default
203             * language.
204             * </p>
205             *
206             * @param doAsUserLanguageId the language ID of the user to impersonate
207             */
208            public void setDoAsUserLanguageId(String doAsUserLanguageId);
209    
210            /**
211             * Sets whether this URL should be encrypted.
212             *
213             * <p>
214             * In an encrypted URL, the value of every parameter will be encrypted using
215             * the company's key. This allows sensitive information to be placed in the
216             * URL without being vulnerable to snooping.
217             * </p>
218             *
219             * <p>
220             * Note that this is not the same as making a URL {@link #setSecure(boolean)
221             * secure}.
222             * </p>
223             */
224            public void setEncrypt(boolean encrypt);
225    
226            /**
227             * Sets whether this URL should be XML escaped.
228             *
229             * <p>
230             * If a URL is XML escaped, it will automatically have special characters
231             * escaped when it is converted to a string or written to a {@link
232             * java.io.Writer}.
233             * </p>
234             *
235             * @param escapeXml whether this URL should be XML escaped
236             */
237            public void setEscapeXml(boolean escapeXml);
238    
239            /**
240             * Sets the portlet lifecycle of this URL's target portlet.
241             *
242             * <p>
243             * Valid lifecycles are:
244             * </p>
245             *
246             * <ul>
247             * <li>
248             * {@link javax.portlet.PortletRequest#ACTION_PHASE}
249             * </li>
250             * <li>
251             * {@link javax.portlet.PortletRequest#RENDER_PHASE}
252             * </li>
253             * <li>
254             * {@link javax.portlet.PortletRequest#RESOURCE_PHASE}
255             * </li>
256             * </ul>
257             *
258             * @param lifecycle the portlet lifecycle
259             */
260            public void setLifecycle(String lifecycle);
261    
262            /**
263             * Sets the URL parameter to the value.
264             *
265             * @param name the name of the URL parameter
266             * @param value the value of the URL parameter
267             * @param append whether the new value should be appended to any existing
268             *        values for the parameter. If <code>append</code> is
269             *        <code>false</code> any existing values will be overwritten with
270             *        the new value.
271             */
272            public void setParameter(String name, String value, boolean append);
273    
274            /**
275             * Sets the URL parameter the values.
276             *
277             * @param name the name of the URL parameter
278             * @param values the values of the URL parameter
279             * @param append whether the new values should be appended to any existing
280             *        values for the parameter. If <code>append</code> is
281             *        <code>false</code> any existing values will be overwritten with
282             *        the new values.
283             */
284            public void setParameter(String name, String[] values, boolean append);
285    
286            /**
287             * Sets the portlet layout ID.
288             *
289             * @param plid the portlet layout ID
290             */
291            public void setPlid(long plid);
292    
293            /**
294             * Sets the ID of the target portlet.
295             */
296            public void setPortletId(String portletId);
297    
298            /**
299             * Sets the referer layout ID.
300             *
301             * @param refererPlid the referer layout ID
302             */
303            public void setRefererPlid(long refererPlid);
304    
305            public void setRemovedParameterNames(Set<String> removedParamNames);
306    
307    }