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