001    /**
002     * Copyright (c) 2000-2011 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 ID of this URL's target portlet.
060             *
061             * @return the ID of this URL's target portlet
062             */
063            public String getPortletId();
064    
065            /**
066             * Returns 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             * Returns the ID of this URL's target resource.
080             *
081             * @return the ID of this URL's target resource
082             */
083            public String getResourceID();
084    
085            /**
086             * Returns <code>true</code> if this URL is an anchor pointing to the
087             * specified portlet on 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             * Returns <code>true</code> if the render parameters in the current request
097             * should be 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             * Returns <code>true</code> 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             * Returns <code>true</code> 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             * Returns <code>true</code> if the parameter is included in the friendly
125             * URL path.
126             *
127             * @param  name the name of the parameter to check for inclusion in the path
128             * @return whether the parameter is included in the friendly URL path
129             * @see    #addParameterIncludedInPath(String)
130             */
131            public boolean isParameterIncludedInPath(String name);
132    
133            /**
134             * Returns <code>true</code> if this URL is secure (https).
135             *
136             * @return <code>true</code> if this URL is secure; <code>false</code>
137             *         otherwise
138             */
139            public boolean isSecure();
140    
141            /**
142             * Sets the portlet lifecycle of this URL's target portlet.
143             *
144             * <p>
145             * Valid lifecycles are:
146             * </p>
147             *
148             * <ul>
149             * <li>
150             * {@link javax.portlet.PortletRequest#ACTION_PHASE}
151             * </li>
152             * <li>
153             * {@link javax.portlet.PortletRequest#RENDER_PHASE}
154             * </li>
155             * <li>
156             * {@link javax.portlet.PortletRequest#RESOURCE_PHASE}
157             * </li>
158             * </ul>
159             *
160             * @param lifecycle the portlet lifecycle
161             */
162            public void setLifecycle(String lifecycle);
163    
164            /**
165             * Sets the URL parameter to the value.
166             *
167             * @param name the name of the URL parameter
168             * @param value the value of the URL parameter
169             * @param append whether the new value should be appended to any existing
170             *        values for the parameter. If <code>append</code> is
171             *        <code>false</code> any existing values will be overwritten with
172             *        the new value.
173             */
174            public void setParameter(String name, String value, boolean append);
175    
176            /**
177             * Sets the URL parameter the values.
178             *
179             * @param name the name of the URL parameter
180             * @param values the values of the URL parameter
181             * @param append whether the new values should be appended to any existing
182             *        values for the parameter. If <code>append</code> is
183             *        <code>false</code> any existing values will be overwritten with
184             *        the new values.
185             */
186            public void setParameter(String name, String[] values, boolean append);
187    
188            /**
189             * Returns the parameters that are included in the friendly URL path and do
190             * not need to appear in the query string.
191             *
192             * @return the names of the parameters that are included in the friendly URL
193             *         path and do not need to appear in the query string
194             */
195            public Set<String> getParametersIncludedInPath();
196    
197            /**
198             * Sets whether this URL is an anchor pointing to the specified portlet on
199             * the page.
200             *
201             * <p>
202             * An anchor URL will cause the user's browser to automatically jump down to
203             * the specified portlet after the page loads, avoiding the need to scroll.
204             * </p>
205             *
206             * @param anchor whether this URL is an anchor pointing to the specified
207             *        portlet on the page
208             */
209            public void setAnchor(boolean anchor);
210    
211            /**
212             * Sets whether the render parameters in the current request should be
213             * copied to this URL.
214             *
215             * <p>
216             * New parameters set on this URL will appear before the copied render
217             * parameters.
218             * </p>
219             *
220             * @param copyCurrentRenderParameters whether the render parameters in the
221             *        current request should be copied to this URL
222             */
223            public void setCopyCurrentRenderParameters(
224                    boolean copyCurrentRenderParameters);
225    
226            public void setDoAsGroupId(long doAsGroupId);
227    
228            /**
229             * Sets the ID of the user to impersonate.
230             *
231             * <p>
232             * When a page is accessed while impersonating a user, it will appear
233             * exactly as it would to that user.
234             * </p>
235             *
236             * @param doAsUserId the ID of the user to impersonate in the portlet this
237             *        URL points to
238             */
239            public void setDoAsUserId(long doAsUserId);
240    
241            /**
242             * Sets the language ID of the user to impersonate. This will only have an
243             * effect when a user is being impersonated via {@link
244             * #setDoAsUserId(long)}.
245             *
246             * <p>
247             * The language set here will override the impersonated user's default
248             * language.
249             * </p>
250             *
251             * @param doAsUserLanguageId the language ID of the user to impersonate
252             */
253            public void setDoAsUserLanguageId(String doAsUserLanguageId);
254    
255            /**
256             * Sets whether this URL should be encrypted.
257             *
258             * <p>
259             * In an encrypted URL, the value of every parameter will be encrypted using
260             * the company's key. This allows sensitive information to be placed in the
261             * URL without being vulnerable to snooping.
262             * </p>
263             *
264             * <p>
265             * Note that this is not the same as making a URL {@link #setSecure(boolean)
266             * secure}.
267             * </p>
268             */
269            public void setEncrypt(boolean encrypt);
270    
271            /**
272             * Sets whether this URL should be XML escaped.
273             *
274             * <p>
275             * If a URL is XML escaped, it will automatically have special characters
276             * escaped when it is converted to a string or written to a {@link
277             * java.io.Writer}.
278             * </p>
279             *
280             * @param escapeXml whether this URL should be XML escaped
281             */
282            public void setEscapeXml(boolean escapeXml);
283    
284            /**
285             * Sets the portlet layout ID.
286             *
287             * @param plid the portlet layout ID
288             */
289            public void setPlid(long plid);
290    
291            /**
292             * Sets the ID of the target portlet.
293             */
294            public void setPortletId(String portletId);
295    
296            /**
297             * Sets the referer layout ID.
298             *
299             * @param refererPlid the referer layout ID
300             */
301            public void setRefererPlid(long refererPlid);
302    
303    }