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 "blogs". 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 "/-/" 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 "/-/" separator should be 102 * included in friendly URLs, or <code>false</code> if only a 103 * "/" 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 }