001    /**
002     * Copyright (c) 2000-2010 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.util.Map;
018    
019    /**
020     * Provides custom URL mapping for a portlet.
021     *
022     * <p>
023     * Never implement this interface directly, subclass {@link
024     * BaseFriendlyURLMapper} to ensure forward compatibility.
025     * </p>
026     *
027     * @author Brian Myunghun Kim
028     * @author Brian Wing Shun Chan
029     * @author Jorge Ferrer
030     * @see    BaseFriendlyURLMapper
031     * @see    DefaultFriendlyURLMapper
032     * @see    com.liferay.portlet.PortletURLImpl
033     */
034    public interface FriendlyURLMapper {
035    
036            /**
037             * Generates a friendly URL path from the portlet URL object.
038             *
039             * @param  liferayPortletURL the portlet URL object to generate a friendly
040             *                 URL for
041             * @return the generated friendly URL, or <code>null</code> if one cannot be
042             *                 built. Returning <code>null</code> will cause a normal portlet
043             *                 URL to be generated.
044             */
045            public String buildPath(LiferayPortletURL liferayPortletURL);
046    
047            /**
048             * Gets the friendly URL mapping for this portlet.
049             *
050             * <p>
051             * The friendly URL mapping is used by Liferay to identify the portlet a
052             * friendly URL refers to. It generally appears directly after the
053             * <code>/-/</code> in the URL.
054             * </p>
055             *
056             * <p>
057             * For instance, the blogs portlet mapping is &quot;blogs&quot;. This
058             * produces friendly URLs similar to
059             * <code>http://www.liferay.com/web/guest/blog/-/blogs/example-post</code>
060             * </p>
061             *
062             * @return the friendly URL mapping for this portlet, not including any
063             *                 leading or trailing slashes
064             */
065            public String getMapping();
066    
067            /**
068             * Gets the id of this portlet
069             *
070             * @return the id of this portlet, not including the instance id
071             */
072            public String getPortletId();
073    
074            /**
075             * Gets the router for this friendly URL mapper
076             *
077             * @return the router, or <code>null</code> if one has not been set
078             */
079            public Router getRouter();
080    
081            /**
082             * Determines if the friendly URLs for this mapper should include the
083             * friendly URL separator.
084             *
085             * <p>
086             * Typically, friendly URLs will include the separator &quot;/-/&quot;
087             * before the friendly URL mapping. If this method returns
088             * <code>false</code>, a single slash will be used instead.
089             * </p>
090             *
091             * <p>
092             * This method is called by {@link com.liferay.portal.util.PortalImpl} when
093             * a friendly URL is processed.
094             * </p>
095             *
096             * <p>
097             * <b>It is strongly recommended that this method always return
098             * <code>true</code></b>.
099             * </p>
100             *
101             * @return <code>true</code> if the &quot;/-/&quot; separator should be
102             *                 included in friendly URLs, or <code>false</code> if only a
103             *                 &quot;/&quot; should be used
104             */
105            public boolean isCheckMappingWithPrefix();
106    
107            /**
108             * Determines if this portlet is instanceable.
109             *
110             * <p>
111             * The value returned from this method has no effect on whether a portlet is
112             * instanceable, it is a helper method used to determine if the instance id
113             * should be included in the URL.
114             * </p>
115             *
116             * @return <code>true</code> if the portlet is instanceable;
117             *                 <code>false</code> otherwise
118             */
119            public boolean isPortletInstanceable();
120    
121            /**
122             * Populates the parameter map with values parsed from the friendly URL
123             * path.
124             *
125             * <p>
126             * This method is called by {@link com.liferay.portal.util.PortalImpl} when
127             * a friendly URL is processed.
128             * </p>
129             *
130             * @param friendlyURLPath the friendly URL path to parse, including a
131             *                leading slash and the friendly URL mapping. For example:
132             *                <code>/blogs/example-post</code>
133             * @param parameterMap the parameter map to populate. Entries added to this
134             *                map must be namespaced.
135             * @param requestContext the request context
136             * @see   BaseFriendlyURLMapper#addParameter(Map, String, String)
137             * @see   BaseFriendlyURLMapper#addParameter(String, Map, String, String)
138             */
139            public void populateParams(
140                    String friendlyURLPath, Map<String, String[]> parameterMap,
141                    Map<String, Object> requestContext);
142    
143            /**
144             * Sets the friendly URL mapping for this portlet.
145             *
146             * <p>
147             * This method is automatically called by {@link
148             * com.liferay.portlet.PortletBagFactory} with the friendly URL mapping
149             * defined in <code>liferay-portlet.xml</code>.
150             * </p>
151             *
152             * @param mapping the friendly URL mapping for this portlet
153             */
154            public void setMapping(String mapping);
155    
156            /**
157             * Sets the id of this portlet.
158             *
159             * <p>
160             * This method is automatically called by {@link
161             * com.liferay.portlet.PortletBagFactory} with the portlet id defined in
162             * <code>liferay-portlet.xml</code>.
163             * </p>
164             *
165             * @param portletId the id of this portlet.
166             */
167            public void setPortletId(String portletId);
168    
169            /**
170             * Sets whether this portlet is instanceable.
171             *
172             * @param portletInstanceable whether this portlet is instanceable
173             */
174            public void setPortletInstanceable(boolean portletInstanceable);
175    
176            /**
177             * Sets the router for this friendly URL mapper.
178             *
179             * <p>
180             * This method is automatically called by {@link
181             * com.liferay.portlet.PortletBagFactory} with a router populated with the
182             * routes defined in this portlet's <a
183             * href="../definitions/liferay-friendly-url-routes_6_0_0.dtd.html"
184             * >friendly-url-routes.xml</a> file. The location of this file is defined
185             * in this portlet's <a
186             * href="../definitions/liferay-portlet-app_6_0_0.dtd.html"
187             * >liferay-portlet.xml</a> file.
188             * </p>
189             *
190             * @param router the router for this friendly URL mapper
191             */
192            public void setRouter(Router router);
193    
194    }