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             * &lt;route&gt;
063             *      &lt;pattern&gt;/{jspPageName}/{id:\d+}&lt;/pattern&gt;
064             *      &lt;generated-parameter name=&quot;jspPage&quot;&gt;{jspPageName}.jsp&lt;/generated-parameter&gt;
065             * &lt;/route&gt;
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             * &lt;route&gt;
116             *      &lt;pattern&gt;/profile/view/{id:\d+}&lt;/pattern&gt;
117             *      &lt;implicit-parameter name=&quot;jspPage&quot;&gt;view_profile.jsp&lt;/implicit-parameter&gt;
118             * &lt;/route&gt;
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    }