001    /**
002     * Copyright (c) 2000-2012 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            /**
075             * Returns the map of reserved parameters for this URL.
076             *
077             * <p>
078             * This method is only used internally. Reserved parameters contain special,
079             * Liferay specific information, such as <code>p_p_id</code> and
080             * <code>p_p_lifecycle</code>.
081             * </p>
082             *
083             * @return the reserved parameter names and values in a read-only map
084             */
085            public Map<String, String> getReservedParameterMap();
086    
087            /**
088             * Returns the ID of this URL's target resource.
089             *
090             * @return the ID of this URL's target resource
091             */
092            public String getResourceID();
093    
094            /**
095             * Returns <code>true</code> if this URL is an anchor pointing to the
096             * specified portlet on the page.
097             *
098             * @return whether this URL is an anchor pointing to the specified portlet
099             *         on the page
100             * @see    #setAnchor(boolean)
101             */
102            public boolean isAnchor();
103    
104            /**
105             * Returns <code>true</code> if the render parameters in the current request
106             * should be copied to this URL.
107             *
108             * @return whether the render parameters in the current request should be
109             *         copied to this URL
110             * @see    #setCopyCurrentRenderParameters(boolean)
111             */
112            public boolean isCopyCurrentRenderParameters();
113    
114            /**
115             * Returns <code>true</code> if this URL should be encrypted.
116             *
117             * @return <code>true</code> if this URL should be encrypted;
118             *         <code>false</code> otherwise
119             * @see    #setEncrypt(boolean)
120             */
121            public boolean isEncrypt();
122    
123            /**
124             * Returns <code>true</code> if this URL should be XML escaped.
125             *
126             * @return <code>true</code> if this URL should be XML escaped;
127             *         <code>false</code> otherwise
128             * @see    #setEscapeXml(boolean)
129             */
130            public boolean isEscapeXml();
131    
132            /**
133             * Returns <code>true</code> if the parameter is included in the friendly
134             * URL path.
135             *
136             * @param  name the name of the parameter to check for inclusion in the path
137             * @return whether the parameter is included in the friendly URL path
138             * @see    #addParameterIncludedInPath(String)
139             */
140            public boolean isParameterIncludedInPath(String name);
141    
142            /**
143             * Returns <code>true</code> if this URL is secure (https).
144             *
145             * @return <code>true</code> if this URL is secure; <code>false</code>
146             *         otherwise
147             */
148            public boolean isSecure();
149    
150            /**
151             * Sets whether this URL is an anchor pointing to the specified portlet on
152             * the page.
153             *
154             * <p>
155             * An anchor URL will cause the user's browser to automatically jump down to
156             * the specified portlet after the page loads, avoiding the need to scroll.
157             * </p>
158             *
159             * @param anchor whether this URL is an anchor pointing to the specified
160             *        portlet on the page
161             */
162            public void setAnchor(boolean anchor);
163    
164            public void setControlPanelCategory(String controlPanelCategory);
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    }