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