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 com.liferay.portal.kernel.util.StringParser; 018 019 import java.util.Map; 020 import java.util.Set; 021 022 /** 023 * Represents a single friendly URL pattern and provides the ability to either 024 * parse a friendly URL path or generate a friendly URL from a parameter map. 025 * 026 * @author Connor McKay 027 * @author Brian Wing Shun Chan 028 * @see Router 029 * @see com.liferay.portlet.RouteImpl 030 * @see com.liferay.portal.kernel.util.StringParser 031 */ 032 public interface Route { 033 034 /** 035 * Adds a generated parameter to this route. 036 * 037 * <p> 038 * A generated parameter is never part of the URL, but is constructed from 039 * one or more "virtual parameters" using a pattern string. When a URL is 040 * parsed, the virtual parameters are populated from the URL, and the 041 * generated parameter is then built from its constituent virtual 042 * parameters. 043 * </p> 044 * 045 * <p> 046 * When a URL is generated, the opposite process occurs. The generated 047 * parameter must have its value passed in through the parameter map. This 048 * value is parsed using the pattern string, and the virtual parameters are 049 * populated and made available for use in the route pattern string. The 050 * value of the generated parameter will not be available in the route 051 * pattern; only the values of the virtual parameters may be used. 052 * </p> 053 * 054 * <p> 055 * The following is an example route definition that uses a generated 056 * parameter to remove the .jsp extension of the current page from the URL. 057 * </p> 058 * 059 * <p> 060 * <pre> 061 * <code> 062 * <route> 063 * <pattern>/{jspPageName}/{id:\d+}</pattern> 064 * <generated-parameter name="jspPage">{jspPageName}.jsp</generated-parameter> 065 * </route> 066 * </code> 067 * </pre> 068 * </p> 069 * 070 * @param name the name of the generated parameter 071 * @param pattern the pattern string of the generated parameter 072 */ 073 public void addGeneratedParameter(String name, String pattern); 074 075 /** 076 * Adds an ignored parameter to this route. 077 * 078 * <p> 079 * An ignored parameter never appears in the query string regardless of its 080 * value. Ignored parameters have no effect on the parsing of URLs. 081 * </p> 082 * 083 * @param name the name of the ignored parameter 084 */ 085 public void addIgnoredParameter(String name); 086 087 /** 088 * Adds an implicit parameter to this route. 089 * 090 * <p> 091 * An implicit parameter applies in both stages of a route's lifecycle, URL 092 * parsing and URL generation. When a URL is parsed, the implicit parameters 093 * will be copied onto the parameter map. When a URL is generated from a 094 * parameter map, all the implicit parameters will be checked against the 095 * parameters in the map. If any do not match or are missing from the 096 * parameter map, this route will not be used for generating the URL. 097 * </p> 098 * 099 * <p> 100 * Implicit parameters are matched after all virtual parameters have been 101 * populated, and therefore should not match against the value of a 102 * generated parameter, as it will not be available. 103 * </p> 104 * 105 * <p> 106 * The most common use of implicit parameters is to specify a parameter that 107 * is included statically in the route pattern. For instance, if a custom 108 * route is specified for the JSP page "view_profile.jsp", the routes 109 * definition could look like the following: 110 * </p> 111 * 112 * <p> 113 * <pre> 114 * <code> 115 * <route> 116 * <pattern>/profile/view/{id:\d+}</pattern> 117 * <implicit-parameter name="jspPage">view_profile.jsp</implicit-parameter> 118 * </route> 119 * </code> 120 * </pre> 121 * </p> 122 * 123 * <p> 124 * Since the jspPage is specified with a implicit-parameter, this route will 125 * only be used to generate URLs if the jspPage is set to 126 * "view_profile.jsp". Likewise, when a URL in this format is recognized, 127 * the jspPage will automatically be set to "view_profile.jsp". 128 * </p> 129 * 130 * @param name the name of the implicit parameter 131 * @param value the value of the implicit parameter 132 */ 133 public void addImplicitParameter(String name, String value); 134 135 /** 136 * Adds an overridden parameter to this route. 137 * 138 * <p> 139 * An overridden parameter is one that should always be set to a certain 140 * value when a URL is parsed. Overridden parameters have no effect on the 141 * generating of URLs. 142 * </p> 143 * 144 * <p> 145 * If a implicit parameter and an overridden parameter share the same name, 146 * the overridden parameter value will take precedence when a URL is parsed. 147 * When a URL is generated the implicit parameter value will be checked 148 * against the parameter map as usual. 149 * </p> 150 * 151 * @param name the name of the overridden parameter 152 * @param value the value of the overridden parameter 153 */ 154 public void addOverriddenParameter(String name, String value); 155 156 /** 157 * Returns the generated parameters for this route. 158 * 159 * @return the generated parameter names and string parsers 160 * @see #addGeneratedParameter(String, String) 161 */ 162 public Map<String, StringParser> getGeneratedParameters(); 163 164 /** 165 * Returns the ignored parameters for this route. 166 * 167 * @return the ignored parameter names 168 * @see #addIgnoredParameter(String) 169 */ 170 public Set<String> getIgnoredParameters(); 171 172 /** 173 * Returns the implicit parameters for this route. 174 * 175 * @return the implicit parameter names and values 176 * @see #addImplicitParameter(String, String) 177 */ 178 public Map<String, String> getImplicitParameters(); 179 180 /** 181 * Returns the overridden parameters for this route. 182 * 183 * @return the overridden parameter names and values 184 * @see #addOverriddenParameter(String, String) 185 */ 186 public Map<String, String> getOverriddenParameters(); 187 188 /** 189 * Generates a URL from the parameter map if this route is appropriate. 190 * 191 * <p> 192 * A route is appropriate if: 193 * </p> 194 * 195 * <ol> 196 * <li> 197 * The values given in <code>parameters</code> for the route's generated 198 * parameters match their patterns 199 * </li> 200 * <li> 201 * The route's implicit parameters all match <code>parameters</code> 202 * </li> 203 * <li> 204 * Every fragment in the route pattern has a matching value in 205 * <code>parameters</code> 206 * </li> 207 * </ol> 208 * 209 * @param parameters the parameter map 210 * @return the URL path, or <code>null</code> if this route is not 211 * appropriate 212 */ 213 public String parametersToUrl(Map<String, String> parameters); 214 215 /** 216 * Populates the parameter map with values parsed from the URL if this route 217 * matches. 218 * 219 * <p> 220 * Generated parameters will be built and added to <code>parameters</code> 221 * if possible. If the pattern for a virtual parameter in the generated 222 * parameter does not match its pattern in the route, that generated 223 * parameter may not be build. 224 * </p> 225 * 226 * <p> 227 * Virtual parameters will not be present in <code>parameters</code>. 228 * </p> 229 * 230 * @param url the URL path 231 * @param parameters the parameter map. If this route does not match, the 232 * parameter map will not be modified. 233 * @return <code>true</code> if the route matches; <code>false</code> 234 * otherwise 235 */ 236 public boolean urlToParameters(String url, Map<String, String> parameters); 237 238 }